Create a company
curl --request POST \
--url https://api.folk.app/v1/companies \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Tech Corp",
"description": "A brief description of the company.",
"fundingRaised": 100000,
"lastFundingDate": "1990-01-01",
"industry": "Technology",
"foundationYear": "1990",
"employeeRange": "51-200",
"groups": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
}
],
"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",
"Business type": [
"B2B",
"B2C"
],
"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": {
"Custom Notes": "Important client, handle with care.",
"ARR": 42000000,
"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({
name: 'Tech Corp',
description: 'A brief description of the company.',
fundingRaised: 100000,
lastFundingDate: '1990-01-01',
industry: 'Technology',
foundationYear: '1990',
employeeRange: '51-200',
groups: [{id: 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
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',
'Business type': ['B2B', 'B2C'],
'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': {
'Custom Notes': 'Important client, handle with care.',
ARR: 42000000,
Assignee: [{id: 'usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6'}, {email: 'jane@example.com'}]
}
}
})
};
fetch('https://api.folk.app/v1/companies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/companies"
payload = {
"name": "Tech Corp",
"description": "A brief description of the company.",
"fundingRaised": 100000,
"lastFundingDate": "1990-01-01",
"industry": "Technology",
"foundationYear": "1990",
"employeeRange": "51-200",
"groups": [{ "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
"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",
"Business type": ["B2B", "B2C"],
"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": {
"Custom Notes": "Important client, handle with care.",
"ARR": 42000000,
"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/companies")
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 \"name\": \"Tech Corp\",\n \"description\": \"A brief description of the company.\",\n \"fundingRaised\": 100000,\n \"lastFundingDate\": \"1990-01-01\",\n \"industry\": \"Technology\",\n \"foundationYear\": \"1990\",\n \"employeeRange\": \"51-200\",\n \"groups\": [\n {\n \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\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 \"Business type\": [\n \"B2B\",\n \"B2C\"\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 \"Custom Notes\": \"Important client, handle with care.\",\n \"ARR\": 42000000,\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/companies"
payload := strings.NewReader("{\n \"name\": \"Tech Corp\",\n \"description\": \"A brief description of the company.\",\n \"fundingRaised\": 100000,\n \"lastFundingDate\": \"1990-01-01\",\n \"industry\": \"Technology\",\n \"foundationYear\": \"1990\",\n \"employeeRange\": \"51-200\",\n \"groups\": [\n {\n \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\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 \"Business type\": [\n \"B2B\",\n \"B2C\"\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 \"Custom Notes\": \"Important client, handle with care.\",\n \"ARR\": 42000000,\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/companies",
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([
'name' => 'Tech Corp',
'description' => 'A brief description of the company.',
'fundingRaised' => 100000,
'lastFundingDate' => '1990-01-01',
'industry' => 'Technology',
'foundationYear' => '1990',
'employeeRange' => '51-200',
'groups' => [
[
'id' => 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
]
],
'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',
'Business type' => [
'B2B',
'B2C'
],
'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' => [
'Custom Notes' => 'Important client, handle with care.',
'ARR' => 42000000,
'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": "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"
}
]
}
}
}
}{
"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"
}
}Companies
Create a company
Create a new company in the workspace.
POST
/
v1
/
companies
Create a company
curl --request POST \
--url https://api.folk.app/v1/companies \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Tech Corp",
"description": "A brief description of the company.",
"fundingRaised": 100000,
"lastFundingDate": "1990-01-01",
"industry": "Technology",
"foundationYear": "1990",
"employeeRange": "51-200",
"groups": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
}
],
"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",
"Business type": [
"B2B",
"B2C"
],
"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": {
"Custom Notes": "Important client, handle with care.",
"ARR": 42000000,
"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({
name: 'Tech Corp',
description: 'A brief description of the company.',
fundingRaised: 100000,
lastFundingDate: '1990-01-01',
industry: 'Technology',
foundationYear: '1990',
employeeRange: '51-200',
groups: [{id: 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
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',
'Business type': ['B2B', 'B2C'],
'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': {
'Custom Notes': 'Important client, handle with care.',
ARR: 42000000,
Assignee: [{id: 'usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6'}, {email: 'jane@example.com'}]
}
}
})
};
fetch('https://api.folk.app/v1/companies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/companies"
payload = {
"name": "Tech Corp",
"description": "A brief description of the company.",
"fundingRaised": 100000,
"lastFundingDate": "1990-01-01",
"industry": "Technology",
"foundationYear": "1990",
"employeeRange": "51-200",
"groups": [{ "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
"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",
"Business type": ["B2B", "B2C"],
"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": {
"Custom Notes": "Important client, handle with care.",
"ARR": 42000000,
"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/companies")
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 \"name\": \"Tech Corp\",\n \"description\": \"A brief description of the company.\",\n \"fundingRaised\": 100000,\n \"lastFundingDate\": \"1990-01-01\",\n \"industry\": \"Technology\",\n \"foundationYear\": \"1990\",\n \"employeeRange\": \"51-200\",\n \"groups\": [\n {\n \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\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 \"Business type\": [\n \"B2B\",\n \"B2C\"\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 \"Custom Notes\": \"Important client, handle with care.\",\n \"ARR\": 42000000,\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/companies"
payload := strings.NewReader("{\n \"name\": \"Tech Corp\",\n \"description\": \"A brief description of the company.\",\n \"fundingRaised\": 100000,\n \"lastFundingDate\": \"1990-01-01\",\n \"industry\": \"Technology\",\n \"foundationYear\": \"1990\",\n \"employeeRange\": \"51-200\",\n \"groups\": [\n {\n \"id\": \"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\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 \"Business type\": [\n \"B2B\",\n \"B2C\"\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 \"Custom Notes\": \"Important client, handle with care.\",\n \"ARR\": 42000000,\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/companies",
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([
'name' => 'Tech Corp',
'description' => 'A brief description of the company.',
'fundingRaised' => 100000,
'lastFundingDate' => '1990-01-01',
'industry' => 'Technology',
'foundationYear' => '1990',
'employeeRange' => '51-200',
'groups' => [
[
'id' => 'grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
]
],
'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',
'Business type' => [
'B2B',
'B2C'
],
'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' => [
'Custom Notes' => 'Important client, handle with care.',
'ARR' => 42000000,
'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": "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"
}
]
}
}
}
}{
"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 company in the workspace, optionally adding them to one or more groups. In the app, companies without groups will only be visible through the “Search” section.
Company names are unique across the workspace. If you try to create a company
with a name that already exists, the existing company will be returned.
Authorizations
API key for authentication
Body
application/json
The name of the company.
Maximum string length:
1000Example:
"Tech Corp"
A short description of the company.
Maximum string length:
5000Example:
"A brief description of the company."
The amount of funding raised by the company in USD, as a number.
Example:
100000
The date of the last funding round for the company, in YYYY-MM-DD format.
Required string length:
10Example:
"1990-01-01"
The industry the company operates in.
Maximum string length:
1000Example:
"Technology"
The foundation year of the company, in YYYY format as string.
Required string length:
4Pattern:
^\d{4}$Example:
"1990"
The employee range of the company.
Available options:
1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10000+ Example:
"51-200"
The groups to add the company to. You must provide group ids.
Maximum array length:
100Show child attributes
Show child attributes
Example:
[ { "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" } ]
A list of addresses associated with the company. The first address in the list will be the company'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 company. The first email address in the list will be the company'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 company. The first phone number in the list will be the company's primary phone number.
Maximum array length:
20Maximum string length:
30Example:
["+1234567890", "+0987654321"]
A list of URLs associated with the company. The first URL in the list will be the company's primary URL.
Maximum array length:
20Maximum string length:
2048Example:
[ "https://example.com", "https://example.com/about" ]
The custom field values associated with the company, 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", "Business type": ["B2B", "B2C"], "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": { "Custom Notes": "Important client, handle with care.", "ARR": 42000000, "Assignee": [ { "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6" }, { "email": "jane@example.com" } ] } }
Response
The company created in the workspace.
A company in the workspace.
Show child attributes
Show child attributes
Example:
{ "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" } ] } } }
Example:
["This field is deprecated"]
⌘I