---
title: "Update companies in batch"
method: POST
path: "/v1/companies/batch/update"
tags: ["Companies"]
---

# Update companies in batch

`POST /v1/companies/batch/update`

## Request

- Base URL: `https://api.folk.app`
- URL: `https://api.folk.app/v1/companies/batch/update`
- Auth: HTTP bearer

Update up to 100 existing companies in the workspace, each with the fields `PATCH /v1/companies/{companyId}` accepts. Each record is updated on its own: one that fails does not prevent the others from being updated.

Fields with a list of values (`groups`, `addresses`, `emails`, `phones`, `urls`) will **replace the old values**. This means that you must provide the entire list of values for that field, not just the values you want to add.

**`groups` replaces the groups of the company, and removing a group deletes data.** A group you can access that is missing from `groups` is removed from the company, together with the company's custom field values in that group. This is the opposite of `POST /v1/companies/batch/create`, where `groups` only adds. Leave `groups` out to keep the company's groups unchanged. Each result lists the groups it removed in `removedGroups`.

**A name must stay unique.** A record renaming a company to the name of another company fails, as in `PATCH /v1/companies/{companyId}`, and so do all the records renaming different companies to the same name, whatever their order. A company that another record of the batch renames still holds its name when the batch is checked.

The records of one company, by its ID or by the ID of a company merged into it, are merged into one update, in request order: the last value given for a field wins, and `customFieldValues` are merged group by group, the last value given for a custom field winning. The merged update is validated as a whole: if it is invalid, every record of that company fails with that error. Each of those records gets its own result, with the company as finally updated.

## Headers

- `Idempotency-Key` string: 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.

## Request body

- object
  - `records` object[], required
    - `id` string, required: The ID of the company to update.
    - `name` string: The name of the company.
    - `description` string: A short description of the company.
    - `fundingRaised` union
      - number: The amount of funding raised by the company in USD, as a number.
      - string: The amount of funding raised by the company in USD, as a string.
    - `lastFundingDate` string, date, nullable: The date of the last funding round for the company, in YYYY-MM-DD format.
    - `industry` string, nullable: The industry the company operates in.
    - `foundationYear` union
      - string: The foundation year of the company, in YYYY format as string.
      - number: The foundation year of the company, in YYYY format as number.
    - `employeeRange` '1-10' | '11-50' | '51-200' | '201-500' | '501-1000' | '1001-5000' | '5001-10000' | '10000+', nullable: The employee range of the company.
    - `groups` object[]: The groups the company must be in after the update, replacing its current groups: a group you can access that is not listed is removed, with the custom field values of the company in it. Leave it out to keep the current groups. You must provide group ids.
      - `id` string, required
    - `addresses` string[]: A list of addresses associated with the company. The first address in the list will be the company's primary address.
    - `emails` string[]: A list of email addresses associated with the company. The first email address in the list will be the company's primary email address.
    - `phones` string[]: A list of phone numbers associated with the company. The first phone number in the list will be the company's primary phone number.
    - `urls` string[]: A list of URLs associated with the company. The first URL in the list will be the company's primary URL.
    - `customFieldValues` object: The custom field values associated with the company, grouped by group ids. The format is the following: ```json { "<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.

## Response `200`

The outcome of each record, with each updated company.

- object
  - `data` object, required
    - `results` union[], required: One result per record, in the order of `records`: the first result is the outcome of the first record.
      - union
        - object
          - `status` 'succeeded', required
          - `data` Company, required: A company in the workspace.
            - `id` string, required
            - `name` string, required: The name of the company.
            - `description` string, required: A short description of the company.
            - `fundingRaised` string, nullable, required: The amount in USD of funding raised by the company.
            - `lastFundingDate` string, date, nullable, required: The date of the last funding round for the company, in YYYY-MM-DD format.
            - `industry` string, nullable, required: The industry the company operates in.
            - `foundationYear` string, nullable, required: The foundation year of the company, in YYYY format.
            - `employeeRange` string, nullable, required: The employee range of the company. Possible values are: "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10000+".
            - `groups` object[], required: The groups associated with the company.
              - …
            - `addresses` string[], required
            - `emails` string[], required
            - `phones` string[], required
            - `urls` string[], required
            - `createdAt` string, nullable, required: The date and time the company was created, in ISO format.
            - `createdBy` User, required: A user in the workspace.
              - …
            - `customFieldValues` object, required
          - `removedGroups` object[], required: The groups this update removed the company from, along with its custom field values in them.
            - `id` string, required
          - `warnings` string[]: What could not be applied to this record although it succeeded, such as a group it could not be added to.
        - object
          - `status` 'failed', required
          - `error` BatchRecordError, required: Why this record did not succeed.
            - `code` string, required
            - `message` string, required
            - `documentationUrl` string, uri, required
            - `details` object
  - `deprecations` string[]

## Other responses

- `400`: The request was unacceptable, often due to missing an invalid parameter.
- `401`: No valid API key provided.
- `403`: The API key doesn’t have permissions to perform the request.
- `404`: The requested resource doesn’t exist.
- `409`: A request with the same `Idempotency-Key` is still being processed, or the resource is in a state that does not allow the operation.
- `422`: The request was unacceptable, often due to missing or invalid parameters.
- `429`: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
- `500`: Something went wrong on our end.
- `503`: The server is overloaded or down for maintenance.

## Changes

- **2026-11-03** `c6818f3ba60d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/folk/apis/folk-external-api/changes/v1/companies/batch/update/post.md)

---

[API](https://skmtc.dev/folk/apis/folk-external-api.md) - [All operations](https://skmtc.dev/folk/apis/folk-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/folk/apis/folk-external-api/revisions/c6818f3ba60d?raw)