FOfolk
Companies

Update a company

Changed on

Update an existing company in the workspace.

patch/v1/companies/{companyId}

Request

  • Base URL
    https://api.folk.app
  • URL
    https://api.folk.app/v1/companies/{companyId}
  • Auth
    HTTP bearer

Path parameters

companyIdstring required

The ID of the company to update.

Headers

Idempotency-Keystring

A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.

Example:8e03978e-40d5-43e8-bc93-6894a57f9324

Request body

namestring

The name of the company.

descriptionstring

A short description of the company.

lastFundingDatestring date nullable

The date of the last funding round for the company, in YYYY-MM-DD format.

industrystring nullable

The industry the company operates in.

employeeRange'1-10' | '11-50' | '51-200' | '201-500' | '501-1000' | '1001-5000' | '5001-10000' | '10000+' nullable

The employee range of the company.

addressesstring[]

A list of addresses associated with the company. The first address in the list will be the company's primary address.

emailsstring[]

A list of email addresses associated with the company. The first email address in the list will be the company's primary email address.

phonesstring[]

A list of phone numbers associated with the company. The first phone number in the list will be the company's primary phone number.

urlsstring[]

A list of URLs associated with the company. The first URL in the list will be the company's primary URL.

customFieldValuesobject

The custom field values associated with the company, grouped by group ids. The format is the following:

{
  "<groupId>": {
    "<customFieldName>": "<customFieldValue>"
  }
}

The group ids passed must also be provided in the groups field, otherwise a validation error will be thrown.

The format of the custom field value depends on the type of the custom field:

  • textField: string, eg: "Foo"
  • numericField: number or numeric string, eg: 42 or "42"
  • dateField: ISO 8601 string (YYYY-MM-DD), eg: "2021-01-01"
  • singleSelect: string (option label), eg: "Active". Use the exact option labels of the custom field (case-sensitive): an unknown label creates a new option.
  • multipleSelect: array of strings (option labels), eg: ["B2B", "B2C"]. Use the exact option labels of the custom field (case-sensitive): an unknown label creates a new option.
  • contactField: array of objects with id property, eg: [{"id": "per_20228901-ce2b-418c-a267-671823107d8c"}]
  • userField: array of objects with either id (workspace user id) or email (workspace user email) property, eg: [{"id": "usr_a23373bb-5296-4c59-b2e8-8f121707d562"}, {"email": "jane@example.com"}]
  • objectField: array of objects with id property, eg: [{"id": "obj_2f62707c-52c0-421a-a11f-68e1ce9610f4"}]

Passing a null value or an empty array will unset the custom field value.

Example request

{
  "name": "Tech Corp",
  "description": "A brief description of the company.",
  "fundingRaised": 100000,
  "lastFundingDate": "1990-01-01",
  "industry": "Technology",
  "foundationYear": "1990",
  "employeeRange": "51-200",
  "groups": [
    {
      "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
    }
  ],
  "addresses": [
    "123 Main St, Springfield, USA",
    "456 Main St, Springfield, USA"
  ],
  "emails": [
    "john@example.com",
    "john@techcorp.com"
  ],
  "phones": [
    "+1234567890",
    "+0987654321"
  ],
  "urls": [
    "https://example.com",
    "https://example.com/about"
  ],
  "customFieldValues": {
    "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
      "Status": "Active",
      "Business type": [
        "B2B",
        "B2C"
      ],
      "Join date": "2021-01-01",
      "Relationships": [
        {
          "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f"
        },
        {
          "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03"
        }
      ]
    },
    "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
      "Custom Notes": "Important client, handle with care.",
      "ARR": 42000000,
      "Assignee": [
        {
          "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
        },
        {
          "email": "jane@example.com"
        }
      ]
    }
  }
}

Response

The updated company in the workspace.

deprecationsstring[]

Example response

{
  "data": {
    "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
    "name": "Tech Corp",
    "description": "A leading technology company.",
    "fundingRaised": "5000000",
    "lastFundingDate": "1990-01-01",
    "industry": "Technology",
    "foundationYear": "1990",
    "employeeRange": "51-200",
    "groups": [
      {
        "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
        "name": "Engineering"
      }
    ],
    "addresses": [
      "123 Main St, Springfield, USA",
      "456 Main St, Springfield, USA"
    ],
    "emails": [
      "john@example.com",
      "john@techcorp.com"
    ],
    "phones": [
      "+1234567890",
      "+0987654321"
    ],
    "urls": [
      "https://example.com"
    ],
    "createdAt": "2021-01-01T00:00:00.000Z",
    "createdBy": {
      "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
      "fullName": "John Doe",
      "email": "john.doe@example.com"
    },
    "customFieldValues": {
      "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
        "Status": "Active",
        "Business type": [
          "B2B",
          "B2C"
        ],
        "Join date": "2021-01-01",
        "Relationships": [
          {
            "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f",
            "fullName": "Bob Smith",
            "entityType": "person"
          },
          {
            "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03",
            "fullName": "HR services",
            "entityType": "company"
          }
        ]
      },
      "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
        "Custom Notes": "Important client, handle with care.",
        "ARR": "42000000",
        "Assignee": [
          {
            "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
            "fullName": "Jane Doe",
            "email": "jane@example.com"
          }
        ]
      }
    }
  },
  "deprecations": [
    "This field is deprecated"
  ]
}

Changes

  • c6818f3ba60dRevision changes
    • info

      the endpoint scheme security bearerApiKeyAuth was added to the API

    • info

      added the new optional header request parameter Idempotency-Key

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the success response with the status