OpenAPI Specification
openapi: 3.0.3
info:
title: Folk External Companies Groups 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: Groups
description: Operations related to groups.
paths:
/v1/groups:
get:
security:
- bearerApiKeyAuth: []
operationId: listGroups
summary: List groups
description: Returns a list of workspace groups.
tags:
- Groups
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
responses:
'200':
description: A paginated list of groups in the workspace. The `data.items` field contains the list of groups, and the `data.pagination.nextLink` field contains a link to the next page of results, if available.
links:
listGroupCustomFields:
operationId: listGroupCustomFields
parameters:
groupId: $response.body#/data/items/0/id
description: The ids returned by the `/v1/groups` operation can be used as an input to the `/v1/groups/:groupId/custom-fields/:entityType` operation, to retrieve the custom fields for a specific group.
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/Group'
pagination:
type: object
properties:
nextLink:
type: string
required:
- items
- pagination
example:
items:
- id: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
name: Group Name
pagination:
nextLink: https://api.folk.app/v1/groups?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
items:
- id: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
name: Group Name
pagination:
nextLink: https://api.folk.app/v1/groups?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'
/v1/groups/{groupId}/custom-fields/{entityType}:
get:
security:
- bearerApiKeyAuth: []
x-stability-level: alpha
operationId: listGroupCustomFields
summary: List group custom fields
description: Returns a list of group custom fields for an entity type.
tags:
- Groups
parameters:
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The identifier of the group. You can retrieve a list of group identifiers using the `/v1/groups` endpoint.
example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
name: groupId
in: path
- schema:
type: string
maxLength: 500
required: true
description: The entity type the custom fields belong to. It can be `person`, `company`, or a custom object name.
example: person
name: entityType
in: path
- 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
responses:
'200':
description: A paginated list of group custom fields for an entity type. The `data.items` field contains the list of group custom fields, and the `data.pagination.nextLink` field contains a link to the next page of results, if available.
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/GroupCustomField'
pagination:
type: object
properties:
nextLink:
type: string
required:
- items
- pagination
example:
items:
- name: Status
type: singleSelect
options:
- label: Active
color: '#ffffff'
- label: Inactive
color: '#000000'
- name: Total Revenue
type: numericField
config:
format: currency
currency: USD
- name: Details
type: textField
- name: Tags
type: multipleSelect
options:
- label: Tag 1
color: '#ffffff'
- label: Tag 2
color: '#000000'
- name: Relationships
type: contactField
- name: Date
type: dateField
- name: Assigned to
type: userField
- name: Deals
type: objectField
pagination:
nextLink: https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/custom-fields/person?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
items:
- name: Status
type: singleSelect
options:
- label: Active
color: '#ffffff'
- label: Inactive
color: '#000000'
- name: Total Revenue
type: numericField
config:
format: currency
currency: USD
- name: Details
type: textField
- name: Tags
type: multipleSelect
options:
- label: Tag 1
color: '#ffffff'
- label: Tag 2
color: '#000000'
- name: Relationships
type: contactField
- name: Date
type: dateField
- name: Assigned to
type: userField
- name: Deals
type: objectField
pagination:
nextLink: https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/custom-fields/person?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'
components:
responses:
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'
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'
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'
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'
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'
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'
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'
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'
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'
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'
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'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMIT_EXCEEDED
message: The rate limit has been exceeded.
documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
requestId: 123e4567-e89b-12d3-a456-426614174000
timestamp: '2025-10-01T12:00:00Z'
details:
limit: 1000
remaining: 0
retryAfter: '2025-10-01T12:00:00Z'
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'
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'
schemas:
GroupCustomField:
type: object
properties:
name:
type: string
type:
type: string
enum:
- multipleSelect
- userField
- contactField
- objectField
- singleSelect
- textField
- dateField
- numericField
options:
type: array
items:
type: object
properties:
label:
type: string
color:
type: string
required:
- label
- color
config:
type: object
properties:
format:
type: string
enum:
- default
- percent
- currency
- none
- number
currency:
type: string
required:
- name
- type
description: A group custom field.
example:
name: Status
type: singleSelect
options:
- label: Active
color: '#ffffff'
- label: Inactive
color: '#000000'
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: RATE_LIMIT_EXCEEDED
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:
limit: 1000
remaining: 0
retryAfter: '2025-10-01T12:00:00Z'
required:
- code
- message
- documentationUrl
- requestId
- timestamp
required:
- error
description: Error response containing error details.
Group:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
description: A group in the workspace.
example:
id: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
name: Group Name
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.
Retry-After:
schema:
type: integer
example: 60
description: The number of seconds to wait before making a new request after hitting the rate limit.
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-Remaining:
schema:
type: integer
example: 998
description: The number of requests remaining in the current rate limit window.
securitySchemes:
bearerApiKeyAuth:
type: http
scheme: bearer
description: API key for authentication