Update companies in batch

curl --request POST \
  --url https://api.folk.app/v1/companies/batch/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
      "industry": "Software",
      "urls": [
        "https://techcorp.com"
      ],
      "customFieldValues": {
        "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
          "Status": "Active"
        }
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    records: [
      {
        id: 'com_183ed5cc-3182-45de-84d1-d520f2604810',
        industry: 'Software',
        urls: ['https://techcorp.com'],
        customFieldValues: {'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2': {Status: 'Active'}}
      }
    ]
  })
};

fetch('https://api.folk.app/v1/companies/batch/update', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.folk.app/v1/companies/batch/update"

payload = { "records": [
        {
            "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
            "industry": "Software",
            "urls": ["https://techcorp.com"],
            "customFieldValues": { "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": { "Status": "Active" } }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

require 'uri'
require 'net/http'

url = URI("https://api.folk.app/v1/companies/batch/update")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"records\": [\n    {\n      \"id\": \"com_183ed5cc-3182-45de-84d1-d520f2604810\",\n      \"industry\": \"Software\",\n      \"urls\": [\n        \"https://techcorp.com\"\n      ],\n      \"customFieldValues\": {\n        \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\": {\n          \"Status\": \"Active\"\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.folk.app/v1/companies/batch/update"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.folk.app/v1/companies/batch/update",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'records' => [
        [
                'id' => 'com_183ed5cc-3182-45de-84d1-d520f2604810',
                'industry' => 'Software',
                'urls' => [
                                'https://techcorp.com'
                ],
                'customFieldValues' => [
                                'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2' => [
                                                                'Status' => 'Active'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $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"
        }
      }
    ]
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request was invalid.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#bad-request",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No valid API key provided.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unauthorized",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The API key doesn’t have permissions to perform the request.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#forbidden",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
    "message": "A request with the same Idempotency-Key is still being processed. Retry once it has completed.",
    "documentationUrl": "https://developer.folk.app/api-reference/idempotency#errors",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Invalid query parameters",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
    "details": {
      "issues": [
        {
          "code": "too_small",
          "minimum": 1,
          "type": "number",
          "inclusive": true,
          "exact": false,
          "message": "Number must be greater than or equal to 1",
          "path": [
            "limit"
          ]
        }
      ]
    },
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "You have exceeded your rate limit.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z",
    "details": {
      "policy": "burst",
      "limit": 20,
      "remaining": 0,
      "windowSeconds": 2,
      "retryAfter": "2025-10-01T12:00:02.000Z",
      "policies": [
        {
          "policy": "default",
          "limit": 600,
          "remaining": 412,
          "windowSeconds": 60,
          "retryAfter": "2025-10-01T12:01:00.000Z"
        },
        {
          "policy": "burst",
          "limit": 20,
          "remaining": 0,
          "windowSeconds": 2,
          "retryAfter": "2025-10-01T12:00:02.000Z"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error occurred.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#internal-server-error",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is currently unavailable.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#service-unavailable",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

Companies

Update companies in batch

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

companies

batch

update

Update companies in batch

curl --request POST \
  --url https://api.folk.app/v1/companies/batch/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
      "industry": "Software",
      "urls": [
        "https://techcorp.com"
      ],
      "customFieldValues": {
        "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
          "Status": "Active"
        }
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    records: [
      {
        id: 'com_183ed5cc-3182-45de-84d1-d520f2604810',
        industry: 'Software',
        urls: ['https://techcorp.com'],
        customFieldValues: {'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2': {Status: 'Active'}}
      }
    ]
  })
};

fetch('https://api.folk.app/v1/companies/batch/update', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.folk.app/v1/companies/batch/update"

payload = { "records": [
        {
            "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
            "industry": "Software",
            "urls": ["https://techcorp.com"],
            "customFieldValues": { "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": { "Status": "Active" } }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

require 'uri'
require 'net/http'

url = URI("https://api.folk.app/v1/companies/batch/update")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"records\": [\n    {\n      \"id\": \"com_183ed5cc-3182-45de-84d1-d520f2604810\",\n      \"industry\": \"Software\",\n      \"urls\": [\n        \"https://techcorp.com\"\n      ],\n      \"customFieldValues\": {\n        \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\": {\n          \"Status\": \"Active\"\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.folk.app/v1/companies/batch/update"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.folk.app/v1/companies/batch/update",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'records' => [
        [
                'id' => 'com_183ed5cc-3182-45de-84d1-d520f2604810',
                'industry' => 'Software',
                'urls' => [
                                'https://techcorp.com'
                ],
                'customFieldValues' => [
                                'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2' => [
                                                                'Status' => 'Active'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $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"
        }
      }
    ]
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request was invalid.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#bad-request",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No valid API key provided.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unauthorized",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The API key doesn’t have permissions to perform the request.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#forbidden",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
    "message": "A request with the same Idempotency-Key is still being processed. Retry once it has completed.",
    "documentationUrl": "https://developer.folk.app/api-reference/idempotency#errors",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Invalid query parameters",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
    "details": {
      "issues": [
        {
          "code": "too_small",
          "minimum": 1,
          "type": "number",
          "inclusive": true,
          "exact": false,
          "message": "Number must be greater than or equal to 1",
          "path": [
            "limit"
          ]
        }
      ]
    },
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "You have exceeded your rate limit.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z",
    "details": {
      "policy": "burst",
      "limit": 20,
      "remaining": 0,
      "windowSeconds": 2,
      "retryAfter": "2025-10-01T12:00:02.000Z",
      "policies": [
        {
          "policy": "default",
          "limit": 600,
          "remaining": 412,
          "windowSeconds": 60,
          "retryAfter": "2025-10-01T12:01:00.000Z"
        },
        {
          "policy": "burst",
          "limit": 20,
          "remaining": 0,
          "windowSeconds": 2,
          "retryAfter": "2025-10-01T12:00:02.000Z"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error occurred.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#internal-server-error",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is currently unavailable.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#service-unavailable",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

Update up to 100 existing companies in the workspace, identified by their id. Each record takes the same fields as update a company, native fields and customFieldValues alike, and is updated on its own: a record that fails, for instance because its id matches no company you can access, does not prevent the others from being updated. See batch requests for the 100-record limit and how to read the response.

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. Leave groups out to keep the company’s groups unchanged.This is the opposite of create companies in batch, where groups only adds.

Each succeeded result lists, in removedGroups, the groups the update removed the company from, empty when it removed none.

Company names

A company name is unique in the workspace, so a rename can fail:

A record renaming a company to the name of another company fails, with the same error as update a company.
Records renaming different companies to the same new name all fail, whatever their order: the batch cannot give one name to two companies.
A company keeps its current name while the batch is checked. Renaming Acme to Acme Corp and another company to Acme in the same batch fails the second record: send it in a later request.

Names match exactly, case included: renaming a company to acme while another is named Acme succeeds.

Records for the same company

The records of one company, by its id or by the id of a company merged into it, are merged into one update, in the order you sent them: the last value given for a field wins, and customFieldValues are merged group by group, the last value given for a custom field winning. Two records giving the same company the same name are one rename, not a collision. 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. This is not always the same as sending the records one after the other: a record setting a custom field value in a group fails, together with the other records of its company, when a later record of that company leaves the group out of groups, where sent first on its own it would succeed. Each updated company comes back in full, as in the response of update a company. A record that was updated but not entirely, for instance because the company could not be added to one of its groups, succeeds with a warnings list explaining what was not applied.

Authorizations

Authorization

string

header

required

API key for authentication

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.

Maximum string length: 255

Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Body

application/json

records

object[]

required

Maximum array length: 100

Show child attributes

Response

The outcome of each record, with each updated company.

data

object

required

Show child attributes

Example:

{
  "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

string[]

Example:

["This field is deprecated"]

Introducton

Available endpoints

Update companies in batch

Company names

Records for the same company

Authorizations

Headers

Body

Response

​Company names

​Records for the same company

Authorizations

Headers

Body

Response

Company names

Records for the same company