Create a person
curl --request POST \
--url https://api.folk.app/v1/people \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"description": "A brief description of the person.",
"birthday": "1990-01-01",
"gender": "Unknown",
"jobTitle": "Software Engineer",
"groups": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
}
],
"companies": [
{
"name": "Tech Corp"
},
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
}
],
"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",
"https://example.com/about"
],
"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"
},
{
"id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03"
}
]
},
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"Favorite color": "Blue",
"Favorite number": 42,
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
},
{
"email": "jane@example.com"
}
]
}
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
firstName: 'John',
lastName: 'Doe',
fullName: 'John Doe',
description: 'A brief description of the person.',
birthday: '1990-01-01',
gender: 'Unknown',
jobTitle: 'Software Engineer',
groups: [{id: 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
companies: [{name: 'Tech Corp'}, {id: 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'}],
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', 'https://example.com/about'],
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'},
{id: 'com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03'}
]
},
'grp_acdf2ad9-6a66-4d32-8594-9694913ac717': {
'Favorite color': 'Blue',
'Favorite number': 42,
Assignee: [{id: 'usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6'}, {email: 'jane@example.com'}]
}
}
})
};
fetch('https://api.folk.app/v1/people', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/people"
payload = {
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"description": "A brief description of the person.",
"birthday": "1990-01-01",
"gender": "Unknown",
"jobTitle": "Software Engineer",
"groups": [{ "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
"companies": [{ "name": "Tech Corp" }, { "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c" }],
"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", "https://example.com/about"],
"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" }, { "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03" }]
},
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"Favorite color": "Blue",
"Favorite number": 42,
"Assignee": [{ "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6" }, { "email": "jane@example.com" }]
}
}
}
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")
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 \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"fullName\": \"John Doe\",\n \"description\": \"A brief description of the person.\",\n \"birthday\": \"1990-01-01\",\n \"gender\": \"Unknown\",\n \"jobTitle\": \"Software Engineer\",\n \"groups\": [\n {\n \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n }\n ],\n \"companies\": [\n {\n \"name\": \"Tech Corp\"\n },\n {\n \"id\": \"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c\"\n }\n ],\n \"addresses\": [\n \"123 Main St, Springfield, USA\",\n \"456 Main St, Springfield, USA\"\n ],\n \"emails\": [\n \"john@example.com\",\n \"john@techcorp.com\"\n ],\n \"phones\": [\n \"+1234567890\",\n \"+0987654321\"\n ],\n \"urls\": [\n \"https://example.com\",\n \"https://example.com/about\"\n ],\n \"customFieldValues\": {\n \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\": {\n \"Status\": \"Active\",\n \"Programming languages\": [\n \"Javascript\",\n \"Python\"\n ],\n \"Join date\": \"2021-01-01\",\n \"Relationships\": [\n {\n \"id\": \"per_ed110a47-5d09-43bf-b2e2-791d8231eb5f\"\n },\n {\n \"id\": \"com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03\"\n }\n ]\n },\n \"grp_acdf2ad9-6a66-4d32-8594-9694913ac717\": {\n \"Favorite color\": \"Blue\",\n \"Favorite number\": 42,\n \"Assignee\": [\n {\n \"id\": \"usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6\"\n },\n {\n \"email\": \"jane@example.com\"\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"
payload := strings.NewReader("{\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"fullName\": \"John Doe\",\n \"description\": \"A brief description of the person.\",\n \"birthday\": \"1990-01-01\",\n \"gender\": \"Unknown\",\n \"jobTitle\": \"Software Engineer\",\n \"groups\": [\n {\n \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n }\n ],\n \"companies\": [\n {\n \"name\": \"Tech Corp\"\n },\n {\n \"id\": \"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c\"\n }\n ],\n \"addresses\": [\n \"123 Main St, Springfield, USA\",\n \"456 Main St, Springfield, USA\"\n ],\n \"emails\": [\n \"john@example.com\",\n \"john@techcorp.com\"\n ],\n \"phones\": [\n \"+1234567890\",\n \"+0987654321\"\n ],\n \"urls\": [\n \"https://example.com\",\n \"https://example.com/about\"\n ],\n \"customFieldValues\": {\n \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\": {\n \"Status\": \"Active\",\n \"Programming languages\": [\n \"Javascript\",\n \"Python\"\n ],\n \"Join date\": \"2021-01-01\",\n \"Relationships\": [\n {\n \"id\": \"per_ed110a47-5d09-43bf-b2e2-791d8231eb5f\"\n },\n {\n \"id\": \"com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03\"\n }\n ]\n },\n \"grp_acdf2ad9-6a66-4d32-8594-9694913ac717\": {\n \"Favorite color\": \"Blue\",\n \"Favorite number\": 42,\n \"Assignee\": [\n {\n \"id\": \"usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6\"\n },\n {\n \"email\": \"jane@example.com\"\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",
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([
'firstName' => 'John',
'lastName' => 'Doe',
'fullName' => 'John Doe',
'description' => 'A brief description of the person.',
'birthday' => '1990-01-01',
'gender' => 'Unknown',
'jobTitle' => 'Software Engineer',
'groups' => [
[
'id' => 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
]
],
'companies' => [
[
'name' => 'Tech Corp'
],
[
'id' => 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'
]
],
'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',
'https://example.com/about'
],
'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'
],
[
'id' => 'com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03'
]
]
],
'grp_acdf2ad9-6a66-4d32-8594-9694913ac717' => [
'Favorite color' => 'Blue',
'Favorite number' => 42,
'Assignee' => [
[
'id' => 'usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6'
],
[
'email' => 'jane@example.com'
]
]
]
]
]),
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": {
"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"
}
}
}
}{
"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": "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": "RATE_LIMIT_EXCEEDED",
"message": "The rate limit has been exceeded.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z",
"details": {
"limit": 1000,
"remaining": 0,
"retryAfter": "2025-10-01T12:00:00Z"
}
}
}{
"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
Create a person
Create a new person in the workspace.
POST
/
v1
/
people
Create a person
curl --request POST \
--url https://api.folk.app/v1/people \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"description": "A brief description of the person.",
"birthday": "1990-01-01",
"gender": "Unknown",
"jobTitle": "Software Engineer",
"groups": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
}
],
"companies": [
{
"name": "Tech Corp"
},
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
}
],
"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",
"https://example.com/about"
],
"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"
},
{
"id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03"
}
]
},
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"Favorite color": "Blue",
"Favorite number": 42,
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
},
{
"email": "jane@example.com"
}
]
}
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
firstName: 'John',
lastName: 'Doe',
fullName: 'John Doe',
description: 'A brief description of the person.',
birthday: '1990-01-01',
gender: 'Unknown',
jobTitle: 'Software Engineer',
groups: [{id: 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
companies: [{name: 'Tech Corp'}, {id: 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'}],
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', 'https://example.com/about'],
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'},
{id: 'com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03'}
]
},
'grp_acdf2ad9-6a66-4d32-8594-9694913ac717': {
'Favorite color': 'Blue',
'Favorite number': 42,
Assignee: [{id: 'usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6'}, {email: 'jane@example.com'}]
}
}
})
};
fetch('https://api.folk.app/v1/people', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/people"
payload = {
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"description": "A brief description of the person.",
"birthday": "1990-01-01",
"gender": "Unknown",
"jobTitle": "Software Engineer",
"groups": [{ "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
"companies": [{ "name": "Tech Corp" }, { "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c" }],
"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", "https://example.com/about"],
"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" }, { "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03" }]
},
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"Favorite color": "Blue",
"Favorite number": 42,
"Assignee": [{ "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6" }, { "email": "jane@example.com" }]
}
}
}
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")
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 \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"fullName\": \"John Doe\",\n \"description\": \"A brief description of the person.\",\n \"birthday\": \"1990-01-01\",\n \"gender\": \"Unknown\",\n \"jobTitle\": \"Software Engineer\",\n \"groups\": [\n {\n \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n }\n ],\n \"companies\": [\n {\n \"name\": \"Tech Corp\"\n },\n {\n \"id\": \"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c\"\n }\n ],\n \"addresses\": [\n \"123 Main St, Springfield, USA\",\n \"456 Main St, Springfield, USA\"\n ],\n \"emails\": [\n \"john@example.com\",\n \"john@techcorp.com\"\n ],\n \"phones\": [\n \"+1234567890\",\n \"+0987654321\"\n ],\n \"urls\": [\n \"https://example.com\",\n \"https://example.com/about\"\n ],\n \"customFieldValues\": {\n \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\": {\n \"Status\": \"Active\",\n \"Programming languages\": [\n \"Javascript\",\n \"Python\"\n ],\n \"Join date\": \"2021-01-01\",\n \"Relationships\": [\n {\n \"id\": \"per_ed110a47-5d09-43bf-b2e2-791d8231eb5f\"\n },\n {\n \"id\": \"com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03\"\n }\n ]\n },\n \"grp_acdf2ad9-6a66-4d32-8594-9694913ac717\": {\n \"Favorite color\": \"Blue\",\n \"Favorite number\": 42,\n \"Assignee\": [\n {\n \"id\": \"usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6\"\n },\n {\n \"email\": \"jane@example.com\"\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"
payload := strings.NewReader("{\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"fullName\": \"John Doe\",\n \"description\": \"A brief description of the person.\",\n \"birthday\": \"1990-01-01\",\n \"gender\": \"Unknown\",\n \"jobTitle\": \"Software Engineer\",\n \"groups\": [\n {\n \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n }\n ],\n \"companies\": [\n {\n \"name\": \"Tech Corp\"\n },\n {\n \"id\": \"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c\"\n }\n ],\n \"addresses\": [\n \"123 Main St, Springfield, USA\",\n \"456 Main St, Springfield, USA\"\n ],\n \"emails\": [\n \"john@example.com\",\n \"john@techcorp.com\"\n ],\n \"phones\": [\n \"+1234567890\",\n \"+0987654321\"\n ],\n \"urls\": [\n \"https://example.com\",\n \"https://example.com/about\"\n ],\n \"customFieldValues\": {\n \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\": {\n \"Status\": \"Active\",\n \"Programming languages\": [\n \"Javascript\",\n \"Python\"\n ],\n \"Join date\": \"2021-01-01\",\n \"Relationships\": [\n {\n \"id\": \"per_ed110a47-5d09-43bf-b2e2-791d8231eb5f\"\n },\n {\n \"id\": \"com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03\"\n }\n ]\n },\n \"grp_acdf2ad9-6a66-4d32-8594-9694913ac717\": {\n \"Favorite color\": \"Blue\",\n \"Favorite number\": 42,\n \"Assignee\": [\n {\n \"id\": \"usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6\"\n },\n {\n \"email\": \"jane@example.com\"\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",
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([
'firstName' => 'John',
'lastName' => 'Doe',
'fullName' => 'John Doe',
'description' => 'A brief description of the person.',
'birthday' => '1990-01-01',
'gender' => 'Unknown',
'jobTitle' => 'Software Engineer',
'groups' => [
[
'id' => 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
]
],
'companies' => [
[
'name' => 'Tech Corp'
],
[
'id' => 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'
]
],
'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',
'https://example.com/about'
],
'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'
],
[
'id' => 'com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03'
]
]
],
'grp_acdf2ad9-6a66-4d32-8594-9694913ac717' => [
'Favorite color' => 'Blue',
'Favorite number' => 42,
'Assignee' => [
[
'id' => 'usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6'
],
[
'email' => 'jane@example.com'
]
]
]
]
]),
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": {
"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"
}
}
}
}{
"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": "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": "RATE_LIMIT_EXCEEDED",
"message": "The rate limit has been exceeded.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z",
"details": {
"limit": 1000,
"remaining": 0,
"retryAfter": "2025-10-01T12:00:00Z"
}
}
}{
"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 a person in the workspace, optionally adding them to one or more groups. In the app, people without groups will only be visible through the “Search” section.
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
API key for authentication
Body
application/json
The first name of the person.
Maximum string length:
500Example:
"John"
The last name of the person.
Maximum string length:
500Example:
"Doe"
The full name of the person.
Maximum string length:
1000Example:
"John Doe"
A short description of the person.
Maximum string length:
5000Example:
"A brief description of the person."
The birthday of the person, in ISO format. Deleted with null or empty string.
Required string length:
10Example:
"1990-01-01"
The gender of the person. Authorized values are "Female", "Male", "Unknown", "Other" or null to delete it.
Available options:
Male, Female, Unknown, Other Example:
"Unknown"
The job title of the person.
Maximum string length:
500Example:
"Software Engineer"
The groups to add the person to. You must provide group ids.
Maximum array length:
100Show child attributes
Show child attributes
Example:
[
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
}
]
The companies associated with the person. You can either provide a name or an id. If you provide a name, the company will be created if it does not already exist. The first company in the list will be the person's primary company.
Maximum array length:
20- Option 1
- Option 2
Show child attributes
Show child attributes
Example:
[
{ "name": "Tech Corp" },
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
}
]
A list of addresses associated with the person. The first address in the list will be the person's primary address.
Maximum array length:
20Maximum string length:
500Example:
[
"123 Main St, Springfield, USA",
"456 Main St, Springfield, USA"
]
A list of email addresses associated with the person. The first email address in the list will be the person's primary email address.
Maximum array length:
20Maximum string length:
254Example:
["john@example.com", "john@techcorp.com"]
A list of phone numbers associated with the person. The first phone number in the list will be the person's primary phone number.
Maximum array length:
20Maximum string length:
30Example:
["+1234567890", "+0987654321"]
A list of URLs associated with the person. The first URL in the list will be the person's primary URL.
Maximum array length:
20Maximum string length:
2048Example:
[
"https://example.com",
"https://example.com/about"
]
The custom field values associated with the person, grouped by group ids. The format is the following:
{
"<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:42or"42"dateField: ISO 8601 string (YYYY-MM-DD), eg:"2021-01-01"singleSelect: string (option label), eg:"Active"multipleSelect: array of strings (option labels), eg:["B2B", "B2C"]contactField: array of objects withidproperty, eg:[{"id": "per_20228901-ce2b-418c-a267-671823107d8c"}]userField: array of objects with eitherid(workspace user id) oremail(workspace user email) property, eg:[{"id": "usr_a23373bb-5296-4c59-b2e8-8f121707d562"}, {"email": "jane@example.com"}]objectField: array of objects withidproperty, eg:[{"id": "obj_2f62707c-52c0-421a-a11f-68e1ce9610f4"}]
Passing a null value or an empty array will unset the custom field value.
Show child attributes
Show child attributes
Example:
{
"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"
},
{
"id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03"
}
]
},
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"Favorite color": "Blue",
"Favorite number": 42,
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
},
{ "email": "jane@example.com" }
]
}
}
Response
The person created in the workspace.
A person in the workspace.
Show child attributes
Show child attributes
Example:
{
"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"
}
}
}
Example:
["This field is deprecated"]
⌘I