Create a deal
curl --request POST \
--url https://api.folk.app/v1/groups/{groupId}/{objectType} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Project Alpha",
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
}
],
"people": [
{
"id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
}
],
"customFieldValues": {
"Status": "Active",
"Deal value": "42000",
"Close date": "2021-01-01",
"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: 'Project Alpha',
companies: [{id: 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'}],
people: [{id: 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
customFieldValues: {
Status: 'Active',
'Deal value': '42000',
'Close date': '2021-01-01',
Assignee: [{id: 'usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6'}, {email: 'jane@example.com'}]
}
})
};
fetch('https://api.folk.app/v1/groups/{groupId}/{objectType}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/groups/{groupId}/{objectType}"
payload = {
"name": "Project Alpha",
"companies": [{ "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c" }],
"people": [{ "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
"customFieldValues": {
"Status": "Active",
"Deal value": "42000",
"Close date": "2021-01-01",
"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/groups/{groupId}/{objectType}")
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\": \"Project Alpha\",\n \"companies\": [\n {\n \"id\": \"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c\"\n }\n ],\n \"people\": [\n {\n \"id\": \"per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n }\n ],\n \"customFieldValues\": {\n \"Status\": \"Active\",\n \"Deal value\": \"42000\",\n \"Close date\": \"2021-01-01\",\n \"Assignee\": [\n {\n \"id\": \"usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6\"\n },\n {\n \"email\": \"jane@example.com\"\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/groups/{groupId}/{objectType}"
payload := strings.NewReader("{\n \"name\": \"Project Alpha\",\n \"companies\": [\n {\n \"id\": \"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c\"\n }\n ],\n \"people\": [\n {\n \"id\": \"per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n }\n ],\n \"customFieldValues\": {\n \"Status\": \"Active\",\n \"Deal value\": \"42000\",\n \"Close date\": \"2021-01-01\",\n \"Assignee\": [\n {\n \"id\": \"usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6\"\n },\n {\n \"email\": \"jane@example.com\"\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/groups/{groupId}/{objectType}",
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' => 'Project Alpha',
'companies' => [
[
'id' => 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'
]
],
'people' => [
[
'id' => 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
]
],
'customFieldValues' => [
'Status' => 'Active',
'Deal value' => '42000',
'Close date' => '2021-01-01',
'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": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
"name": "Project Alpha",
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
"name": "Tech Corp"
}
],
"people": [
{
"id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
"fullName": "John Doe"
}
],
"createdAt": "2021-01-01T00:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"customFieldValues": {
"Status": "Active",
"Deal value": "42000",
"Close date": "2021-01-01",
"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"
}
}Custom objects
Create an object
Create a new object of any type in a group.
POST
/
v1
/
groups
/
{groupId}
/
{objectType}
Create a deal
curl --request POST \
--url https://api.folk.app/v1/groups/{groupId}/{objectType} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Project Alpha",
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
}
],
"people": [
{
"id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
}
],
"customFieldValues": {
"Status": "Active",
"Deal value": "42000",
"Close date": "2021-01-01",
"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: 'Project Alpha',
companies: [{id: 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'}],
people: [{id: 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
customFieldValues: {
Status: 'Active',
'Deal value': '42000',
'Close date': '2021-01-01',
Assignee: [{id: 'usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6'}, {email: 'jane@example.com'}]
}
})
};
fetch('https://api.folk.app/v1/groups/{groupId}/{objectType}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/groups/{groupId}/{objectType}"
payload = {
"name": "Project Alpha",
"companies": [{ "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c" }],
"people": [{ "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
"customFieldValues": {
"Status": "Active",
"Deal value": "42000",
"Close date": "2021-01-01",
"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/groups/{groupId}/{objectType}")
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\": \"Project Alpha\",\n \"companies\": [\n {\n \"id\": \"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c\"\n }\n ],\n \"people\": [\n {\n \"id\": \"per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n }\n ],\n \"customFieldValues\": {\n \"Status\": \"Active\",\n \"Deal value\": \"42000\",\n \"Close date\": \"2021-01-01\",\n \"Assignee\": [\n {\n \"id\": \"usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6\"\n },\n {\n \"email\": \"jane@example.com\"\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/groups/{groupId}/{objectType}"
payload := strings.NewReader("{\n \"name\": \"Project Alpha\",\n \"companies\": [\n {\n \"id\": \"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c\"\n }\n ],\n \"people\": [\n {\n \"id\": \"per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n }\n ],\n \"customFieldValues\": {\n \"Status\": \"Active\",\n \"Deal value\": \"42000\",\n \"Close date\": \"2021-01-01\",\n \"Assignee\": [\n {\n \"id\": \"usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6\"\n },\n {\n \"email\": \"jane@example.com\"\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/groups/{groupId}/{objectType}",
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' => 'Project Alpha',
'companies' => [
[
'id' => 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'
]
],
'people' => [
[
'id' => 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
]
],
'customFieldValues' => [
'Status' => 'Active',
'Deal value' => '42000',
'Close date' => '2021-01-01',
'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": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
"name": "Project Alpha",
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
"name": "Tech Corp"
}
],
"people": [
{
"id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
"fullName": "John Doe"
}
],
"createdAt": "2021-01-01T00:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"customFieldValues": {
"Status": "Active",
"Deal value": "42000",
"Close date": "2021-01-01",
"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 new object of a given type in a group.
Set the
objectType path parameter to the name of the object type you want to create — Deals, Projects, Applications, or any other object type defined in the group. See Custom objects to find the object types available in a group.
The body is the same for every object type: the native fields (name, people, companies) plus a customFieldValues object holding the custom fields defined for that object type in the group.
Applications
{
"name": "Jane Doe — Senior Engineer",
"people": [{ "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
"customFieldValues": {
"Status": "Interviewing"
}
}
Custom field names in
customFieldValues must match the custom fields defined
for that object type in the group. An unknown field name fails the whole
request with a 422 Unprocessable Entity response naming the offending field.Authorizations
API key for authentication
Path Parameters
The ID of the group the deals belong to. Can be retrieved from the List groups endpoint.
Required string length:
40The name of a deal custom field that can be retrieved from the List group custom fields endpoint.
Maximum string length:
500Body
application/json
The name of the deal.
Maximum string length:
1000Example:
"Project Alpha"
The companies associated with the deal.
Maximum array length:
20Show child attributes
Show child attributes
Example:
[
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
}
]
The people associated with the deal.
Maximum array length:
20Show child attributes
Show child attributes
Example:
[
{
"id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
}
]
The custom field values associated with the deal. The format is the following:
{
"<customFieldName>": "<customFieldValue>"
}
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"]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"}]
Passing a null value or an empty array will unset the custom field value.
Show child attributes
Show child attributes
Example:
{
"Status": "Active",
"Deal value": "42000",
"Close date": "2021-01-01",
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
},
{ "email": "jane@example.com" }
]
}
Response
The deal created in the workspace.
A deal in the workspace.
Show child attributes
Show child attributes
Example:
{
"id": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
"name": "Project Alpha",
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
"name": "Tech Corp"
}
],
"people": [
{
"id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
"fullName": "John Doe"
}
],
"createdAt": "2021-01-01T00:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"customFieldValues": {
"Status": "Active",
"Deal value": "42000",
"Close date": "2021-01-01",
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
"fullName": "Jane Doe",
"email": "jane@example.com"
}
]
}
}
Example:
["This field is deprecated"]