Create objects in batch

Create deals in batch

curl --request POST \
  --url https://api.folk.app/v1/groups/{groupId}/{objectType}/batch/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "name": "Project Alpha",
      "companies": [
        {
          "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
        }
      ],
      "people": [
        {
          "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
        }
      ],
      "customFieldValues": {
        "Status": "Active"
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    records: [
      {
        name: 'Project Alpha',
        companies: [{id: 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'}],
        people: [{id: 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
        customFieldValues: {Status: 'Active'}
      }
    ]
  })
};

fetch('https://api.folk.app/v1/groups/{groupId}/{objectType}/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/groups/{groupId}/{objectType}/batch/create"

payload = { "records": [
        {
            "name": "Project Alpha",
            "companies": [{ "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c" }],
            "people": [{ "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
            "customFieldValues": { "Status": "Active" }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

require 'uri'
require 'net/http'

url = URI("https://api.folk.app/v1/groups/{groupId}/{objectType}/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      \"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      }\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/groups/{groupId}/{objectType}/batch/create"

	payload := strings.NewReader("{\n  \"records\": [\n    {\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      }\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}/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' => [
        [
                'name' => 'Project Alpha',
                'companies' => [
                                [
                                                                'id' => 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'
                                ]
                ],
                'people' => [
                                [
                                                                'id' => 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
                                ]
                ],
                'customFieldValues' => [
                                'Status' => 'Active'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "results": [
      {
        "status": "succeeded",
        "data": {
          "id": "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"
              }
            ]
          }
        }
      },
      {
        "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

groups

{groupId}

{objectType}

batch

create

Create deals in batch

curl --request POST \
  --url https://api.folk.app/v1/groups/{groupId}/{objectType}/batch/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "name": "Project Alpha",
      "companies": [
        {
          "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
        }
      ],
      "people": [
        {
          "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
        }
      ],
      "customFieldValues": {
        "Status": "Active"
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    records: [
      {
        name: 'Project Alpha',
        companies: [{id: 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'}],
        people: [{id: 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
        customFieldValues: {Status: 'Active'}
      }
    ]
  })
};

fetch('https://api.folk.app/v1/groups/{groupId}/{objectType}/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/groups/{groupId}/{objectType}/batch/create"

payload = { "records": [
        {
            "name": "Project Alpha",
            "companies": [{ "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c" }],
            "people": [{ "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
            "customFieldValues": { "Status": "Active" }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

require 'uri'
require 'net/http'

url = URI("https://api.folk.app/v1/groups/{groupId}/{objectType}/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      \"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      }\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/groups/{groupId}/{objectType}/batch/create"

	payload := strings.NewReader("{\n  \"records\": [\n    {\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      }\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}/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' => [
        [
                'name' => 'Project Alpha',
                'companies' => [
                                [
                                                                'id' => 'com_92346499-30bf-4278-ae8e-4aa3ae2ace2c'
                                ]
                ],
                'people' => [
                                [
                                                                'id' => 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
                                ]
                ],
                'customFieldValues' => [
                                'Status' => 'Active'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "results": [
      {
        "status": "succeeded",
        "data": {
          "id": "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"
              }
            ]
          }
        }
      },
      {
        "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 new objects of a given type in one request. 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. An object type that does not exist in the group fails the whole request with a 404, whose message lists the object types of the group. Each record takes the same fields as create an object and is created on its own: a record that fails, for instance because of an unknown custom field, does not prevent the others from being created. See batch requests for the 100-record limit and how to read the response. Each object comes back in full, as in the response of create an object. If the API key cannot create objects in the group, every record fails.

Objects are never matched with existing ones: two records with the same name, or a record named like an existing object, create separate objects. A batch retried after a timeout or a network error creates every object again. Send an Idempotency-Key header, so that a retry replays the first response instead.

People and companies are given by ID, and must already be in the group: an unknown one, or one not in the group, is ignored. To link people or companies you are importing, create them first with create people in batch or create companies in batch, and use the IDs they return. The objects of a request are created together with their people and companies: if that fails, every record fails and no object is created. A record that succeeded but whose custom field values could not all be set carries a warnings list explaining what was not applied.

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"

Path Parameters

groupId

string

required

The ID of the group the deals belong to. Can be retrieved from the List groups endpoint.

Required string length: 40

objectType

string

required

The name of a deal custom field that can be retrieved from the List group custom fields endpoint.

Maximum string length: 500

Body

application/json

records

object[]

required

Maximum array length: 100

Show child attributes

Response

The outcome of each record, with each created deal.

data

object

required

Show child attributes

Example:

{
  "results": [
    {
      "status": "succeeded",
      "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"
            }
          ]
        }
      }
    },
    {
      "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

Authorizations

Headers

Path Parameters

Body

Response