OpenAPI Specification
openapi: 3.0.3
info:
title: Folk External Companies 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
tags:
- name: Companies
description: Operations related to companies.
paths:
/v1/companies:
get:
security:
- bearerApiKeyAuth: []
operationId: listCompanies
summary: List companies
description: Retrieve a list of companies in the workspace.
tags:
- Companies
parameters:
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
required: false
description: The number of items to return.
example: 20
name: limit
in: query
- schema:
type: string
maxLength: 128
required: false
description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results.
example: eyJvZmZzZXQiOjN9
name: cursor
in: query
- schema:
type: string
enum:
- and
- or
default: and
required: false
description: The logical operator to combine multiple filters.
example: and
name: combinator
in: query
- schema:
type: object
additionalProperties: true
default: {}
properties: {}
required: false
description: A record of filters to apply, following the format `filter[attribute][operator]=value`. The `attribute` is the name of the attribute to filter on, and the `operator` is one of the supported filter operators. Refer to [Filterable fields](/api-reference/filtering#filterable-fields) to learn more about the supported attributes and operators.
style: deepObject
explode: true
allowReserved: true
examples:
fullName_eq:
summary: Full name equals "Alice Johnson"
value:
fullName:
eq: Alice Johnson
fullName_not_eq:
summary: Full name does not equal "Alice Johnson"
value:
fullName:
not_eq: Alice Johnson
fullName_like:
summary: Full name contains "Alice"
value:
fullName:
like: Alice
fullName_not_like:
summary: Full name does not contain "Alice"
value:
fullName:
not_like: Alice
fullName_empty:
summary: Full name is empty
value:
fullName:
empty: ''
fullName_not_empty:
summary: Full name is not empty
value:
fullName:
not_empty: ''
firstName_eq:
summary: First name equals "Alice"
value:
firstName:
eq: Alice
lastName_eq:
summary: Last name equals "Alice"
value:
lastName:
eq: Alice
jobTitle_eq:
summary: Job title equals "Software Engineer"
value:
jobTitle:
eq: Software Engineer
birthday_gt:
summary: Birthday is after "1990-01-01"
value:
birthday:
gt: '1990-01-01'
description_like:
summary: Description contains "developer"
value:
description:
like: developer
emails_eq:
summary: Emails equals "alice@example.com"
value:
emails:
eq: alice@example.com
phones_eq:
summary: Phones equals "123-456-7890"
value:
phones:
eq: 123-456-7890
urls_eq:
summary: URLs equals "https://example.com"
value:
urls:
eq: https://example.com
addresses_eq:
summary: Addresses equals "123 Main St"
value:
addresses:
eq: 123 Main St
companies_in:
summary: Companies includes multiple IDs
value:
companies:
in:
id:
- com_8a5c68a0-6566-4e30-bdd0-382d708277de
- com_d3d63a35-733e-450e-a521-97ed25f5f087
companies_not_in:
summary: Companies does not include "com_8a5c68a0-6566-4e30-bdd0-382d708277de"
value:
companies:
not_in:
id: com_8a5c68a0-6566-4e30-bdd0-382d708277de
companies_empty:
summary: Companies is empty
value:
companies:
empty: ''
companies_not_empty:
summary: Companies is not empty
value:
companies:
not_empty: ''
groups_in:
summary: Groups includes multiple IDs
value:
groups:
in:
id:
- grp_721e5288-324a-4f2e-85bd-4a3469987f97
- grp_bee00bb3-48b4-4033-bc9c-a9d173a94c0e
textField_eq:
summary: Text field equals "Some text value"
value:
customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Text:
eq: Some text value
numericField_gt:
summary: Number field is greater than "42"
value:
customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Number:
gt: '42'
dateField_gt:
summary: Date field is after "2023-01-01"
value:
customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Date:
gt: '2023-01-01'
singleSelect_in:
summary: Single select field includes "Todo" or "In Progress"
value:
customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Single select:
in:
- Todo
- In Progress
multipleSelect_in:
summary: Multiple select field includes "B2B" or "B2C"
value:
customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Multiple select:
in:
- B2B
- B2C
userField_in:
summary: User field includes a user with the email "john@folk.app" or a user with the id "usr_52401927-bf77-4130-a4cb-aceb295eb5b9"
value:
customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Assign:
in:
email: john@folk.app
id: usr_52401927-bf77-4130-a4cb-aceb295eb5b9
contactField_in:
summary: Contact field includes specific IDs
value:
customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Relationship:
in:
id:
- per_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf
- com_4b452b53-22c3-4373-94b8-33ef6eb2788f
name: filter
in: query
responses:
'200':
description: A paginated list of companies in the workspace.
links:
updateCompany:
operationId: updateCompany
parameters:
companyId: $response.body#/data/items/0/id
description: The ids returned by the `GET /v1/companies` operation can be used as an input to the `PATCH /v1/companies/:companyId` operation to update a company.
getCompany:
operationId: getCompany
parameters:
companyId: $response.body#/data/items/0/id
description: The ids returned by the `GET /v1/companies` operation can be used as an input to the `GET /v1/companies/:companyId` operation to retrieve a company.
deleteCompany:
operationId: deleteCompany
parameters:
companyId: $response.body#/data/items/0/id
description: The ids returned by the `GET /v1/companies` operation can be used as an input to the `DELETE /v1/companies/:companyId` operation to delete a 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'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Company'
pagination:
type: object
properties:
nextLink:
type: string
required:
- items
- pagination
example:
items:
- 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
pagination:
nextLink: https://api.folk.app/v1/companies?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
items:
- 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
pagination:
nextLink: https://api.folk.app/v1/companies?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
post:
security:
- bearerApiKeyAuth: []
operationId: createCompany
summary: Create a company
description: Create a new company in the workspace.
tags:
- Companies
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
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'
nullable: true
industry:
type: string
maxLength: 1000
description: The industry the company operates in.
example: Technology
nullable: true
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
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
nullable: true
groups:
type: array
items:
type: object
properties:
id:
type: string
minLength: 40
maxLength: 40
required:
- id
additionalProperties: false
maxItems: 100
description: The groups to add the company to. 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:\n```json\n{\n \"<groupId>\": {\n \"<customFieldName>\": \"<customFieldValue>\"\n }\n}\n```\n\nThe group ids passed must also be provided in the `groups` field, otherwise a validation error will be thrown.\n\nThe format of the custom field value depends on the type of the custom field:\n\n- `textField`: string, eg: `\"Foo\"`\n- `numericField`: number or numeric string, eg: `42` or `\"42\"`\n- `dateField`: ISO 8601 string (YYYY-MM-DD), eg: `\"2021-01-01\"`\n- `singleSelect`: string (option label), eg: `\"Active\"`\n- `multipleSelect`: array of strings (option labels), eg: `[\"B2B\", \"B2C\"]`\n- `contactField`: array of objects with `id` property, eg: `[{\"id\": \"per_20228901-ce2b-418c-a267-671823107d8c\"}]`\n- `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\"}]`\n- `objectField`: array of objects with `id` property, eg: `[{\"id\": \"obj_2f62707c-52c0-421a-a11f-68e1ce9610f4\"}]`\n\nPassing a `null` value or an empty array will unset the custom field value.\n"
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
additionalProperties: false
responses:
'200':
description: The company created in the workspace.
links:
updateCompany:
operationId: updateCompany
parameters:
companyId: $response.body#/data/id
description: The id returned by the `POST /v1/companies` operation can be used as an input to the `PATCH /v1/companies/:companyId` operation to update the company.
getCompany:
operationId: getCompany
parameters:
companyId: $response.body#/data/id
description: The id returned by the `POST /v1/companies` operation can be used as an input to the `GET /v1/companies/:companyId` operation to retrieve the company.
deleteCompany:
operationId: deleteCompany
parameters:
companyId: $response.body#/data/id
description: The id returned by the `POST /v1/companies` operation can be used as an input to the `DELETE /v1/companies/:companyId` operation to delete the 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'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Company'
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
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
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/v1/companies/{companyId}:
get:
security:
- bearerApiKeyAuth: []
operationId: getCompany
summary: Get a company
description: Retrieve an existing company in the workspace.
tags:
- Companies
parameters:
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The ID of the company to retrieve.
name: companyId
in: path
responses:
'200':
description: The retrieved company in the workspace.
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'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Company'
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
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
'400':
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/folk/refs/heads/main/openapi/folk-companies-api-openapi.yml