> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Update companies in batch
> Update up to 100 existing companies in the workspace, each with the fields `PATCH /v1/companies/{companyId}` accepts. Each record is updated on its own: one that fails does not prevent the others from being updated.
Fields with a list of values (`groups`, `addresses`, `emails`, `phones`, `urls`) will **replace the old values**. This means that you must provide the entire list of values for that field, not just the values you want to add.
**`groups` replaces the groups of the company, and removing a group deletes data.** A group you can access that is missing from `groups` is removed from the company, together with the company's custom field values in that group. This is the opposite of `POST /v1/companies/batch/create`, where `groups` only adds. Leave `groups` out to keep the company's groups unchanged. Each result lists the groups it removed in `removedGroups`.
**A name must stay unique.** A record renaming a company to the name of another company fails, as in `PATCH /v1/companies/{companyId}`, and so do all the records renaming different companies to the same name, whatever their order. A company that another record of the batch renames still holds its name when the batch is checked.
The records of one company, by its ID or by the ID of a company merged into it, are merged into one update, in request order: the last value given for a field wins, and `customFieldValues` are merged group by group, 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 company fails with that error. Each of those records gets its own result, with the company as finally updated.
Update up to 100 existing companies in the workspace, identified by their `id`. Each record takes the same fields as [update a company](/api-reference/companies/update-a-company), native fields and `customFieldValues` alike, and is updated on its own: a record that fails, for instance because its `id` matches no company you can access, does not prevent the others from being updated. See [batch requests](/api-reference/batch-requests) for the 100-record limit and how to read the response.
Fields with a list of values (`groups`, `addresses`, `emails`, `phones`,
`urls`) will **replace the old values**. This means that you must provide the
entire list of values for that field, not just the values you want to add.
**`groups` replaces the groups of the company, and removing a group deletes
data.** A group you can access that is missing from `groups` is removed from
the company, together with the company's custom field values in that group.
Leave `groups` out to keep the company's groups unchanged.
This is the opposite of [create companies in batch](/api-reference/companies/create-companies-in-batch),
where `groups` only adds.
Each succeeded result lists, in `removedGroups`, the groups the update removed the company from, empty when it removed none.
## Company names
A company name is unique in the workspace, so a rename can fail:
* A record renaming a company to the name of another company fails, with the same error as [update a company](/api-reference/companies/update-a-company).
* Records renaming different companies to the same new name all fail, whatever their order: the batch cannot give one name to two companies.
* A company keeps its current name while the batch is checked. Renaming `Acme` to `Acme Corp` and another company to `Acme` in the same batch fails the second record: send it in a later request.
Names match exactly, case included: renaming a company to `acme` while another is named `Acme` succeeds.
## Records for the same company
The records of one company, by its `id` or by the `id` of a company merged into it, are merged into one update, in the order you sent them: the last value given for a field wins, and `customFieldValues` are merged group by group, the last value given for a custom field winning. Two records giving the same company the same name are one rename, not a collision. The merged update is validated as a whole: if it is invalid, every record of that company fails with that error. Each of those records gets its own result, with the company as finally updated. This is not always the same as sending the records one after the other: a record setting a custom field value in a group fails, together with the other records of its company, when a later record of that company leaves the group out of `groups`, where sent first on its own it would succeed.
Each updated company comes back in full, as in the response of [update a company](/api-reference/companies/update-a-company). A record that was updated but not entirely, for instance because the company could not be added to one of its groups, succeeds with a `warnings` list explaining what was not applied.
## OpenAPI
````yaml post /v1/companies/batch/update
openapi: 3.1.0
info:
title: Folk External API
description: >-
Folk's public REST API lets you manage workspaces, groups, contacts, and
real-time triggers.
version: '2025-06-09'
contact:
name: folk
email: tech@folk.app
url: https://folk.app
servers:
- url: https://api.folk.app
description: Folk's public API production base URL.
x-internal: false
security: []
tags:
- name: Companies
description: Operations related to companies.
- name: Credits
description: Operations related to credits.
- name: Deals
description: Operations related to deals.
- name: Groups
description: Operations related to groups.
- name: Group members
description: Operations related to group members.
- name: Group custom fields
description: Operations related to group custom fields.
- name: Interactions
description: Operations related to interactions.
- name: Notes
description: Operations related to notes.
- name: People
description: Operations related to people.
- name: Reminders
description: Operations related to reminders.
- name: Tasks
description: Operations related to tasks.
- name: Users
description: Operations related to users.
- name: Webhooks
description: Operations related to webhooks.
paths:
/v1/companies/batch/update:
post:
tags:
- Companies
summary: Update companies in batch
description: >-
Update up to 100 existing companies in the workspace, each with the
fields `PATCH /v1/companies/{companyId}` accepts. Each record is updated
on its own: one that fails does not prevent the others from being
updated.
Fields with a list of values (`groups`, `addresses`, `emails`, `phones`,
`urls`) will **replace the old values**. This means that you must
provide the entire list of values for that field, not just the values
you want to add.
**`groups` replaces the groups of the company, and removing a group
deletes data.** A group you can access that is missing from `groups` is
removed from the company, together with the company's custom field
values in that group. This is the opposite of `POST
/v1/companies/batch/create`, where `groups` only adds. Leave `groups`
out to keep the company's groups unchanged. Each result lists the groups
it removed in `removedGroups`.
**A name must stay unique.** A record renaming a company to the name of
another company fails, as in `PATCH /v1/companies/{companyId}`, and so
do all the records renaming different companies to the same name,
whatever their order. A company that another record of the batch renames
still holds its name when the batch is checked.
The records of one company, by its ID or by the ID of a company merged
into it, are merged into one update, in request order: the last value
given for a field wins, and `customFieldValues` are merged group by
group, 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
company fails with that error. Each of those records gets its own
result, with the company as finally updated.
operationId: batchUpdateCompanies
parameters:
- schema:
type: string
maxLength: 255
description: >-
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.
example: 8e03978e-40d5-43e8-bc93-6894a57f9324
required: false
name: Idempotency-Key
in: header
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
records:
type: array
items:
type: object
properties:
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the company to update.
name:
type: string
maxLength: 1000
description: The name of the company.
example: Tech Corp
description:
type: string
maxLength: 5000
description: A short description of the company.
example: A brief description of the company.
fundingRaised:
anyOf:
- type: number
description: >-
The amount of funding raised by the company in
USD, as a number.
example: 100000
- type: string
minLength: 1
maxLength: 20
description: >-
The amount of funding raised by the company in
USD, as a string.
example: '100000'
- type: 'null'
- type: 'null'
lastFundingDate:
type:
- string
- 'null'
minLength: 10
maxLength: 10
format: date
description: >-
The date of the last funding round for the company, in
YYYY-MM-DD format.
example: '1990-01-01'
industry:
type:
- string
- 'null'
maxLength: 1000
description: The industry the company operates in.
example: Technology
foundationYear:
anyOf:
- type: string
minLength: 4
maxLength: 4
pattern: ^\d{4}$
description: >-
The foundation year of the company, in YYYY format
as string.
example: '1990'
- type: number
minimum: 1000
maximum: 2100
description: >-
The foundation year of the company, in YYYY format
as number.
example: 1990
- type: 'null'
- type: 'null'
employeeRange:
type:
- string
- 'null'
enum:
- 1-10
- 11-50
- 51-200
- 201-500
- 501-1000
- 1001-5000
- 5001-10000
- 10000+
description: The employee range of the company.
example: 51-200
groups:
type: array
items:
type: object
properties:
id:
type: string
minLength: 40
maxLength: 40
required:
- id
additionalProperties: false
maxItems: 100
description: >-
The groups the company must be in after the update,
replacing its current groups: a group you can access
that is not listed is removed, with the custom field
values of the company in it. Leave it out to keep the
current groups. You must provide group ids.
example:
- id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
addresses:
type: array
items:
type: string
maxLength: 500
description: ''
example: ''
maxItems: 20
description: >-
A list of addresses associated with the company. The
first address in the list will be the company's
primary address.
example:
- 123 Main St, Springfield, USA
- 456 Main St, Springfield, USA
emails:
type: array
items:
type: string
maxLength: 254
description: ''
example: ''
maxItems: 20
description: >-
A list of email addresses associated with the company.
The first email address in the list will be the
company's primary email address.
example:
- john@example.com
- john@techcorp.com
phones:
type: array
items:
type: string
maxLength: 30
description: ''
example: ''
maxItems: 20
description: >-
A list of phone numbers associated with the company.
The first phone number in the list will be the
company's primary phone number.
example:
- '+1234567890'
- '+0987654321'
urls:
type: array
items:
type: string
maxLength: 2048
description: ''
example: ''
maxItems: 20
description: >-
A list of URLs associated with the company. The first
URL in the list will be the company's primary URL.
example:
- https://example.com
- https://example.com/about
customFieldValues:
type: object
additionalProperties:
type: object
additionalProperties:
anyOf:
- type: 'null'
- type: string
maxLength: 5000
- type: number
minimum: -1.7976931348623157e+308
maximum: 1.7976931348623157e+308
- type: array
items:
anyOf:
- type: string
maxLength: 500
- type: object
properties:
id:
type: string
minLength: 40
maxLength: 40
required:
- id
- type: object
properties:
email:
type: string
maxLength: 254
required:
- email
maxItems: 1000
- type: 'null'
properties: {}
description: >
The custom field values associated with the company,
grouped by group ids. The format is the following:
```json
{
"": {
"": ""
}
}
```
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: `42`
or `"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 with `id` property,
eg: `[{"id":
"per_20228901-ce2b-418c-a267-671823107d8c"}]`
- `userField`: array of objects with either `id`
(workspace user id) or `email` (workspace user email)
property, eg: `[{"id":
"usr_a23373bb-5296-4c59-b2e8-8f121707d562"}, {"email":
"jane@example.com"}]`
- `objectField`: array of objects with `id` property,
eg: `[{"id":
"obj_2f62707c-52c0-421a-a11f-68e1ce9610f4"}]`
Passing a `null` value or an empty array will unset
the custom field value.
properties: {}
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
required:
- id
additionalProperties: false
example:
id: com_183ed5cc-3182-45de-84d1-d520f2604810
industry: Software
urls:
- https://techcorp.com
customFieldValues:
grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2:
Status: Active
maxItems: 100
required:
- records
example:
records:
- id: com_183ed5cc-3182-45de-84d1-d520f2604810
industry: Software
urls:
- https://techcorp.com
customFieldValues:
grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2:
Status: Active
responses:
'200':
description: The outcome of each record, with each updated company.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
results:
type: array
items:
oneOf:
- type: object
properties:
status:
type: string
enum:
- succeeded
data:
$ref: '#/components/schemas/Company'
removedGroups:
type: array
items:
type: object
properties:
id:
type: string
required:
- id
description: >-
The groups this update removed the company
from, along with its custom field values in
them.
warnings:
type: array
items:
type: string
description: >-
What could not be applied to this record
although it succeeded, such as a group it
could not be added to.
required:
- status
- data
- removedGroups
- type: object
properties:
status:
type: string
enum:
- failed
error:
$ref: '#/components/schemas/BatchRecordError'
required:
- status
- error
description: >-
One result per record, in the order of `records`: the
first result is the outcome of the first record.
required:
- results
example:
results:
- status: succeeded
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
removedGroups:
- id: grp_2b7c9e14-3f8a-4d61-a5e2-7c0d9b4f6a13
- status: failed
error:
code: NOT_FOUND
message: Not found.
documentationUrl: >-
https://developer.folk.app/api-reference/errors#not-found
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
results:
- status: succeeded
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
removedGroups:
- id: grp_2b7c9e14-3f8a-4d61-a5e2-7c0d9b4f6a13
- status: failed
error:
code: NOT_FOUND
message: Not found.
documentationUrl: >-
https://developer.folk.app/api-reference/errors#not-found
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
security:
- bearerApiKeyAuth: []
components:
headers:
X-RateLimit-Limit:
schema:
type: integer
example: 1000
description: >-
The maximum number of requests that you can make in the current rate
limit window.
X-RateLimit-Remaining:
schema:
type: integer
example: 998
description: The number of requests remaining in the current rate limit window.
X-RateLimit-Reset:
schema:
type: integer
example: 1747322958
description: >-
The time at which the current rate limit window resets, in UTC epoch
seconds.
X-RateLimit-Limit-Burst:
schema:
type: integer
example: 20
description: >-
The maximum number of requests that you can make in the current burst
rate limit window.
X-RateLimit-Remaining-Burst:
schema:
type: integer
example: 18
description: The number of requests remaining in the current burst rate limit window.
X-RateLimit-Reset-Burst:
schema:
type: integer
example: 1747322902
description: >-
The time at which the current burst rate limit window resets, in UTC
epoch seconds.
RateLimit-Policy:
schema:
type: string
example: '"default";q=600;w=60, "burst";q=20;w=2'
description: >-
The rate limit policies applied to the request, as defined by the IETF
RateLimit header fields draft. `q` is the number of requests allowed per
window and `w` the window length in seconds.
RateLimit:
schema:
type: string
example: '"default";r=598;t=42, "burst";r=18;t=1'
description: >-
The current usage of each rate limit policy, as defined by the IETF
RateLimit header fields draft. `r` is the number of requests remaining
and `t` the number of seconds until the window resets.
Retry-After:
schema:
type: integer
example: 60
description: >-
The number of seconds to wait before making a new request after hitting
the rate limit.
schemas:
Company:
type: object
properties:
id:
type: string
name:
type: string
description: The name of the company.
example: Tech Corp
description:
type: string
description: A short description of the company.
example: A brief description of the company.
fundingRaised:
type:
- string
- 'null'
description: The amount in USD of funding raised by the company.
example: '5000000'
lastFundingDate:
type:
- string
- 'null'
minLength: 10
maxLength: 10
format: date
description: >-
The date of the last funding round for the company, in YYYY-MM-DD
format.
example: '1990-01-01'
industry:
type:
- string
- 'null'
description: The industry the company operates in.
example: Technology
foundationYear:
type:
- string
- 'null'
description: The foundation year of the company, in YYYY format.
example: '1990'
employeeRange:
type:
- string
- 'null'
description: >-
The employee range of the company. Possible values are: "1-10",
"11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000",
"10000+".
example: 51-200
groups:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
description: The groups associated with the company.
example:
- id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
name: Engineering
addresses:
type: array
items:
type: string
description: >-
An address associated with the company. The first address in the
list is the company's primary address.
example: 123 Main St, Springfield, USA
emails:
type: array
items:
type: string
description: >-
An email address associated with the company. The first email
address in the list is the company's primary email address.
example: john@example.com
phones:
type: array
items:
type: string
description: >-
A phone number associated with the company. The first phone number
in the list is the company's primary phone number.
example: '+1234567890'
urls:
type: array
items:
type: string
description: >-
A URL associated with the company. The first URL in the list is
the company's primary URL.
example: https://example.com
createdAt:
type:
- string
- 'null'
minLength: 20
maxLength: 40
description: The date and time the company was created, in ISO format.
example: '2021-01-01T00:00:00.000Z'
createdBy:
$ref: '#/components/schemas/User'
customFieldValues:
type: object
additionalProperties:
type: object
additionalProperties:
anyOf:
- type: 'null'
- type: string
description: A custom field value as a string.
example: Value 1
- type: array
items:
type: string
description: An array of values for the custom field.
example:
- Value 1
- Value 2
- type: array
items:
$ref: '#/components/schemas/User'
description: An array of users associated with the custom field.
example:
- id: usr_44b85098-441b-4d7f-9d72-c079b1caec45
fullName: Jane Doe
email: jane@example.com
- id: usr_a95a1b90-8e88-4855-bc29-d47b8e2704e1
fullName: John Doe
email: john@example.com
- type: array
items:
anyOf:
- type: object
properties:
id:
type: string
fullName:
type: string
entityType:
type: string
enum:
- person
required:
- id
- fullName
- entityType
- type: object
properties:
id:
type: string
fullName:
type: string
entityType:
type: string
enum:
- company
required:
- id
- fullName
- entityType
- type: object
properties:
id:
type: string
fullName:
type: string
entityType:
type: string
enum:
- object
required:
- id
- fullName
- entityType
description: An array of relationships associated with the custom field.
example:
- id: per_183ed5cc-3182-45de-84d1-d520f2604810
fullName: John Doe
entityType: person
- id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
fullName: Tech Corp
entityType: company
- type: 'null'
required:
- id
- name
- description
- fundingRaised
- lastFundingDate
- industry
- foundationYear
- employeeRange
- groups
- addresses
- emails
- phones
- urls
- createdAt
- createdBy
- customFieldValues
description: A company in the workspace.
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
BatchRecordError:
type: object
properties:
code:
type: string
example: NOT_FOUND
message:
type: string
example: Not found.
documentationUrl:
type: string
format: uri
example: https://developer.folk.app/api-reference/errors#not-found
details:
type: object
additionalProperties: true
required:
- code
- message
- documentationUrl
description: Why this record did not succeed.
example:
code: NOT_FOUND
message: Not found.
documentationUrl: https://developer.folk.app/api-reference/errors#not-found
User:
type: object
properties:
id:
type: string
fullName:
type: string
email:
type: string
required:
- id
- fullName
- email
description: A user in the workspace.
example:
id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
fullName: John Doe
email: john.doe@example.com
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: TOO_MANY_REQUESTS
message:
type: string
example: You have exceeded your rate limit.
documentationUrl:
type: string
format: uri
example: https://developer.folk.app/api-reference/errors#rate-limiting
requestId:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
timestamp:
type: string
format: date-time
example: '2025-10-01T12:00:00Z'
details:
type: object
additionalProperties: true
example:
policy: burst
limit: 20
remaining: 0
windowSeconds: 2
retryAfter: '2025-10-01T12:00:02.000Z'
required:
- code
- message
- documentationUrl
- requestId
- timestamp
required:
- error
description: Error response containing error details.
RateLimitError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: TOO_MANY_REQUESTS
message:
type: string
example: You have exceeded your rate limit.
documentationUrl:
type: string
format: uri
example: https://developer.folk.app/api-reference/errors#rate-limiting
requestId:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
timestamp:
type: string
format: date-time
example: '2025-10-01T12:00:00Z'
details:
type: object
properties:
policy:
type: string
enum:
- default
- burst
description: The name of the rate limit policy.
limit:
type: integer
description: The maximum number of requests allowed per window.
remaining:
type: integer
description: The number of requests remaining in the current window.
windowSeconds:
type: integer
description: The length of the window, in seconds.
retryAfter:
type: string
format: date-time
description: When the current window resets.
policies:
type: array
items:
type: object
properties:
policy:
type: string
enum:
- default
- burst
description: The name of the rate limit policy.
limit:
type: integer
description: The maximum number of requests allowed per window.
remaining:
type: integer
description: >-
The number of requests remaining in the current
window.
windowSeconds:
type: integer
description: The length of the window, in seconds.
retryAfter:
type: string
format: date-time
description: When the current window resets.
required:
- policy
- limit
- remaining
- windowSeconds
- retryAfter
description: >-
The status of every rate limit policy applied to the
request.
required:
- policy
- limit
- remaining
- windowSeconds
- retryAfter
- policies
description: >-
The exceeded rate limit policy. When several are exceeded, the
one resetting last.
required:
- code
- message
- documentationUrl
- requestId
- timestamp
- details
required:
- error
description: Error response returned when a rate limit is exceeded.
responses:
BadRequest:
description: The request was unacceptable, often due to missing an invalid parameter.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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'
Unauthorized:
description: No valid API key provided.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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'
Forbidden:
description: The API key doesn’t have permissions to perform the request.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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'
NotFound:
description: The requested resource doesn’t exist.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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'
Conflict:
description: A request with the same `Idempotency-Key` is still being processed.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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'
UnprocessableEntity:
description: >-
The request was unacceptable, often due to missing or invalid
parameters.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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'
TooManyRequests:
description: >-
Too many requests hit the API too quickly. We recommend an exponential
backoff of your requests.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
example:
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'
InternalServerError:
description: Something went wrong on our end.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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'
ServiceUnavailable:
description: The server is overloaded or down for maintenance.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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'
securitySchemes:
bearerApiKeyAuth:
type: http
scheme: bearer
description: API key for authentication
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.