Update objects in batch

Update deals in batch

curl --request POST \
  --url https://api.folk.app/v1/groups/{groupId}/{objectType}/batch/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "id": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
      "name": "Project Alpha",
      "people": [
        {
          "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
        }
      ],
      "customFieldValues": {
        "Status": "Won"
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    records: [
      {
        id: 'obj_183ed5cc-3182-45de-84d1-d520f2604810',
        name: 'Project Alpha',
        people: [{id: 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
        customFieldValues: {Status: 'Won'}
      }
    ]
  })
};

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

payload = { "records": [
        {
            "id": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
            "name": "Project Alpha",
            "people": [{ "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
            "customFieldValues": { "Status": "Won" }
        }
    ] }
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/update")

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      \"id\": \"obj_183ed5cc-3182-45de-84d1-d520f2604810\",\n      \"name\": \"Project Alpha\",\n      \"people\": [\n        {\n          \"id\": \"per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n        }\n      ],\n      \"customFieldValues\": {\n        \"Status\": \"Won\"\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/update"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"id\": \"obj_183ed5cc-3182-45de-84d1-d520f2604810\",\n      \"name\": \"Project Alpha\",\n      \"people\": [\n        {\n          \"id\": \"per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n        }\n      ],\n      \"customFieldValues\": {\n        \"Status\": \"Won\"\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/update",
  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' => [
        [
                'id' => 'obj_183ed5cc-3182-45de-84d1-d520f2604810',
                'name' => 'Project Alpha',
                'people' => [
                                [
                                                                'id' => 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
                                ]
                ],
                'customFieldValues' => [
                                'Status' => 'Won'
                ]
        ]
    ]
  ]),
  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

update

Update deals in batch

curl --request POST \
  --url https://api.folk.app/v1/groups/{groupId}/{objectType}/batch/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "id": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
      "name": "Project Alpha",
      "people": [
        {
          "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
        }
      ],
      "customFieldValues": {
        "Status": "Won"
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    records: [
      {
        id: 'obj_183ed5cc-3182-45de-84d1-d520f2604810',
        name: 'Project Alpha',
        people: [{id: 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'}],
        customFieldValues: {Status: 'Won'}
      }
    ]
  })
};

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

payload = { "records": [
        {
            "id": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
            "name": "Project Alpha",
            "people": [{ "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" }],
            "customFieldValues": { "Status": "Won" }
        }
    ] }
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/update")

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      \"id\": \"obj_183ed5cc-3182-45de-84d1-d520f2604810\",\n      \"name\": \"Project Alpha\",\n      \"people\": [\n        {\n          \"id\": \"per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n        }\n      ],\n      \"customFieldValues\": {\n        \"Status\": \"Won\"\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/update"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"id\": \"obj_183ed5cc-3182-45de-84d1-d520f2604810\",\n      \"name\": \"Project Alpha\",\n      \"people\": [\n        {\n          \"id\": \"per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2\"\n        }\n      ],\n      \"customFieldValues\": {\n        \"Status\": \"Won\"\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/update",
  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' => [
        [
                'id' => 'obj_183ed5cc-3182-45de-84d1-d520f2604810',
                'name' => 'Project Alpha',
                'people' => [
                                [
                                                                'id' => 'per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2'
                                ]
                ],
                'customFieldValues' => [
                                'Status' => 'Won'
                ]
        ]
    ]
  ]),
  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"
  }
}

Update up to 100 existing objects of a given type in one request, identified by their id. Set the objectType path parameter to the name of the object type you want to update — 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. A record whose id designates an object of another type, or of another group, fails as not found. Each record takes the same fields as update an object and is updated on its own: a record that fails, for instance because of an unknown custom field, does not prevent the others from being updated. 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 update an object. If the API key cannot update objects in the group, every record fails.

people and companies replace the people and companies of the object: you must provide the entire list, not just the ones you want to add. Leave them out to keep them unchanged.

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. The records of one object are merged into one update, in the order you sent them: the last value given for a field wins, and customFieldValues are merged field by field, the last value given for a custom field winning. The merged update is validated as a whole: if it is invalid, every record of that object fails with that error. Each of those records gets its own result, with the object as finally updated. This is not always the same as sending the records one after the other: a record with an invalid custom field value fails every record of its object, including the earlier ones, which sent on their own would have been applied before it. A record that succeeded but whose people, companies or 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 updated 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"]

Introduction

Available endpoints

Authorizations

Headers

Path Parameters

Body

Response