FOfolk
Companies

Update companies in batch

Changed on

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.

post/v1/companies/batch/update

Request

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

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

Example request

{
  "records": [
    {
      "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
      "industry": "Software",
      "urls": [
        "https://techcorp.com"
      ],
      "customFieldValues": {
        "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
          "Status": "Active"
        }
      }
    }
  ]
}

Response

The outcome of each record, with each updated company.

deprecationsstring[]

Example response

{
  "data": {
    "results": [
      {
        "status": "succeeded",
        "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"
                }
              ]
            }
          }
        },
        "removedGroups": [
          {
            "id": "grp_2b7c9e14-3f8a-4d61-a5e2-7c0d9b4f6a13"
          }
        ]
      },
      {
        "status": "failed",
        "error": {
          "code": "NOT_FOUND",
          "message": "Not found.",
          "documentationUrl": "https://developer.folk.app/api-reference/errors#not-found"
        }
      }
    ]
  },
  "deprecations": [
    "This field is deprecated"
  ]
}

Changes