Create people in batch

curl --request POST \
  --url https://api.folk.app/v1/people/batch/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "fullName": "John Doe",
      "jobTitle": "Software Engineer",
      "emails": [
        "john@example.com"
      ],
      "companies": [
        {
          "name": "Example Inc."
        }
      ],
      "groups": [
        {
          "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
        }
      ]
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    records: [
      {
        fullName: 'John Doe',
        jobTitle: 'Software Engineer',
        emails: ['john@example.com'],
        companies: [{name: 'Example Inc.'}],
        groups: [{id: 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}]
      }
    ]
  })
};

fetch('https://api.folk.app/v1/people/batch/create', 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/create"

payload = { "records": [
        {
            "fullName": "John Doe",
            "jobTitle": "Software Engineer",
            "emails": ["john@example.com"],
            "companies": [{ "name": "Example Inc." }],
            "groups": [{ "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }]
        }
    ] }
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/create")

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      \"fullName\": \"John Doe\",\n      \"jobTitle\": \"Software Engineer\",\n      \"emails\": [\n        \"john@example.com\"\n      ],\n      \"companies\": [\n        {\n          \"name\": \"Example Inc.\"\n        }\n      ],\n      \"groups\": [\n        {\n          \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\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/people/batch/create"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"fullName\": \"John Doe\",\n      \"jobTitle\": \"Software Engineer\",\n      \"emails\": [\n        \"john@example.com\"\n      ],\n      \"companies\": [\n        {\n          \"name\": \"Example Inc.\"\n        }\n      ],\n      \"groups\": [\n        {\n          \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\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/create",
  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' => [
        [
                'fullName' => 'John Doe',
                'jobTitle' => 'Software Engineer',
                'emails' => [
                                'john@example.com'
                ],
                'companies' => [
                                [
                                                                'name' => 'Example Inc.'
                                ]
                ],
                'groups' => [
                                [
                                                                'id' => 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
                                ]
                ]
        ]
    ]
  ]),
  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"
            }
          }
        }
      },
      {
        "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"
  }
}

POST

people

batch

create

Create people in batch

curl --request POST \
  --url https://api.folk.app/v1/people/batch/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "fullName": "John Doe",
      "jobTitle": "Software Engineer",
      "emails": [
        "john@example.com"
      ],
      "companies": [
        {
          "name": "Example Inc."
        }
      ],
      "groups": [
        {
          "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
        }
      ]
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    records: [
      {
        fullName: 'John Doe',
        jobTitle: 'Software Engineer',
        emails: ['john@example.com'],
        companies: [{name: 'Example Inc.'}],
        groups: [{id: 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}]
      }
    ]
  })
};

fetch('https://api.folk.app/v1/people/batch/create', 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/create"

payload = { "records": [
        {
            "fullName": "John Doe",
            "jobTitle": "Software Engineer",
            "emails": ["john@example.com"],
            "companies": [{ "name": "Example Inc." }],
            "groups": [{ "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }]
        }
    ] }
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/create")

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      \"fullName\": \"John Doe\",\n      \"jobTitle\": \"Software Engineer\",\n      \"emails\": [\n        \"john@example.com\"\n      ],\n      \"companies\": [\n        {\n          \"name\": \"Example Inc.\"\n        }\n      ],\n      \"groups\": [\n        {\n          \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\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/people/batch/create"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"fullName\": \"John Doe\",\n      \"jobTitle\": \"Software Engineer\",\n      \"emails\": [\n        \"john@example.com\"\n      ],\n      \"companies\": [\n        {\n          \"name\": \"Example Inc.\"\n        }\n      ],\n      \"groups\": [\n        {\n          \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\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/create",
  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' => [
        [
                'fullName' => 'John Doe',
                'jobTitle' => 'Software Engineer',
                'emails' => [
                                'john@example.com'
                ],
                'companies' => [
                                [
                                                                'name' => 'Example Inc.'
                                ]
                ],
                'groups' => [
                                [
                                                                'id' => 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
                                ]
                ]
        ]
    ]
  ]),
  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"
            }
          }
        }
      },
      {
        "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"
  }
}

Create up to 100 people in the workspace, each optionally added to one or more groups. Each record takes the same fields as create a person and is created on its own: a record that fails, for instance because it names a company ID that does not exist, does not prevent the others from being created. See batch requests for the 100-record limit and how to read the response. Every record creates a new person, even when two records are identical or match an existing person. A company given by name is linked to the existing company of that name, or created if there is none. Records naming the same new company are all linked to one created company. Names match exactly, so Acme and acme are two companies. Each created person comes back in full, as in the response of create a person. A record that was created but could not be fully set up, for instance because the person could not be added to one of its groups, succeeds with a warnings list explaining what was not applied.

folk automatically checks for duplicates when creating people. If the system detects a duplicate, the newly created person will be merged in the background, possibly overwriting some of the provided data.

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 created person.

data

object

required

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

Create people in batch

Authorizations

Headers

Body

Response