Update people in batch
curl --request POST \
--url https://api.folk.app/v1/people/batch/update \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"records": [
{
"id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
"jobTitle": "Engineering Manager",
"emails": [
"john@example.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: 'per_183ed5cc-3182-45de-84d1-d520f2604810',
jobTitle: 'Engineering Manager',
emails: ['john@example.com'],
customFieldValues: {'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2': {Status: 'Active'}}
}
]
})
};
fetch('https://api.folk.app/v1/people/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/people/batch/update"
payload = { "records": [
{
"id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
"jobTitle": "Engineering Manager",
"emails": ["john@example.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/people/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\": \"per_183ed5cc-3182-45de-84d1-d520f2604810\",\n \"jobTitle\": \"Engineering Manager\",\n \"emails\": [\n \"john@example.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_bodypackage main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/people/batch/update"
payload := strings.NewReader("{\n \"records\": [\n {\n \"id\": \"per_183ed5cc-3182-45de-84d1-d520f2604810\",\n \"jobTitle\": \"Engineering Manager\",\n \"emails\": [\n \"john@example.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/people/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' => 'per_183ed5cc-3182-45de-84d1-d520f2604810',
'jobTitle' => 'Engineering Manager',
'emails' => [
'john@example.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": "per_183ed5cc-3182-45de-84d1-d520f2604810",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"description": "John Doe is a software engineer at Tech Corp.",
"birthday": "1980-06-15",
"gender": "Female",
"jobTitle": "Software Engineer",
"createdAt": "2021-01-01T00:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"groups": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
"name": "Engineering"
}
],
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
"name": "Tech Corp"
}
],
"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"
],
"customFieldValues": {
"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
"Status": "Active",
"Programming languages": [
"Javascript",
"Python"
],
"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": {
"Favorite color": "Blue",
"Favorite number": "42",
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
"fullName": "Jane Doe",
"email": "jane@example.com"
}
]
}
},
"interactionMetadata": {
"user": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z"
},
"workspace": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z",
"lastInteractedBy": [
{
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
}
]
}
},
"strongestConnection": {
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@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"
}
}People
Update people in batch
Update up to 100 existing people in the workspace, each with the fields PATCH /v1/people/{personId} 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, companies, 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 person, and removing a group deletes data. A group you can access that is missing from groups is removed from the person, together with the person’s custom field values in that group. This is the opposite of POST /v1/people/batch/create, where groups only adds: the same payload adds groups when it creates a person and removes groups when it updates one. Leave groups out to keep the person’s groups unchanged. Each result lists the groups it removed in removedGroups.
The records of one person, by its ID or by the ID of a person 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 person fails with that error. Each of those records gets its own result, with the person as finally updated.
POST
/
v1
/
people
/
batch
/
update
Update people in batch
curl --request POST \
--url https://api.folk.app/v1/people/batch/update \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"records": [
{
"id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
"jobTitle": "Engineering Manager",
"emails": [
"john@example.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: 'per_183ed5cc-3182-45de-84d1-d520f2604810',
jobTitle: 'Engineering Manager',
emails: ['john@example.com'],
customFieldValues: {'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2': {Status: 'Active'}}
}
]
})
};
fetch('https://api.folk.app/v1/people/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/people/batch/update"
payload = { "records": [
{
"id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
"jobTitle": "Engineering Manager",
"emails": ["john@example.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/people/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\": \"per_183ed5cc-3182-45de-84d1-d520f2604810\",\n \"jobTitle\": \"Engineering Manager\",\n \"emails\": [\n \"john@example.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_bodypackage main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/people/batch/update"
payload := strings.NewReader("{\n \"records\": [\n {\n \"id\": \"per_183ed5cc-3182-45de-84d1-d520f2604810\",\n \"jobTitle\": \"Engineering Manager\",\n \"emails\": [\n \"john@example.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/people/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' => 'per_183ed5cc-3182-45de-84d1-d520f2604810',
'jobTitle' => 'Engineering Manager',
'emails' => [
'john@example.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": "per_183ed5cc-3182-45de-84d1-d520f2604810",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"description": "John Doe is a software engineer at Tech Corp.",
"birthday": "1980-06-15",
"gender": "Female",
"jobTitle": "Software Engineer",
"createdAt": "2021-01-01T00:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"groups": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
"name": "Engineering"
}
],
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
"name": "Tech Corp"
}
],
"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"
],
"customFieldValues": {
"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
"Status": "Active",
"Programming languages": [
"Javascript",
"Python"
],
"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": {
"Favorite color": "Blue",
"Favorite number": "42",
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
"fullName": "Jane Doe",
"email": "jane@example.com"
}
]
}
},
"interactionMetadata": {
"user": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z"
},
"workspace": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z",
"lastInteractedBy": [
{
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
}
]
}
},
"strongestConnection": {
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@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 people in the workspace, identified by their
Each succeeded result lists, in
id. Each record takes the same fields as update a person, native fields and customFieldValues alike, and is updated on its own: a record that fails, for instance because its id matches no person 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.
Fields with a list of values (
groups, companies, 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 person, and removing a group deletes
data. A group you can access that is missing from groups is removed from
the person, together with the person’s custom field values in that group.
Leave groups out to keep the person’s groups unchanged.This is the opposite of create people in batch,
where groups only adds. A script that creates a person when it has no id
and updates it otherwise gets opposite results from the same payload: the
create adds the listed groups, the update removes every other group.removedGroups, the groups the update removed the person from, empty when it removed none.
The records of one person, by its id or by the id of a person 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. With "firstName": "Foo" then "firstName": "Bar", the person ends up named Bar. The merged update is validated as a whole: if it is invalid, every record of that person fails with that error. Each of those records gets its own result, with the person as finally updated.
Records naming the same new company, by name, are all linked to one created company. Names match exactly, so Acme and acme are two companies.
Each updated person comes back in full, as in the response of update a person. A record that was updated but not entirely, for instance because the person could not be added to one of its groups, succeeds with a warnings list explaining what was not applied.Authorizations
API key for authentication
Headers
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:
255Example:
"8e03978e-40d5-43e8-bc93-6894a57f9324"
Body
application/json
Maximum array length:
100Show child attributes
Show child attributes
Response
The outcome of each record, with each updated person.
Show child attributes
Show child attributes
Example:
{
"results": [
{
"status": "succeeded",
"data": {
"id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"description": "John Doe is a software engineer at Tech Corp.",
"birthday": "1980-06-15",
"gender": "Female",
"jobTitle": "Software Engineer",
"createdAt": "2021-01-01T00:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"groups": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
"name": "Engineering"
}
],
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
"name": "Tech Corp"
}
],
"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"],
"customFieldValues": {
"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
"Status": "Active",
"Programming languages": ["Javascript", "Python"],
"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": {
"Favorite color": "Blue",
"Favorite number": "42",
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
"fullName": "Jane Doe",
"email": "jane@example.com"
}
]
}
},
"interactionMetadata": {
"user": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z"
},
"workspace": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z",
"lastInteractedBy": [
{
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
}
]
}
},
"strongestConnection": {
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@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"
}
}
]
}
Example:
["This field is deprecated"]