OpenAPI Specification
openapi: 3.0.3
info:
title: Folk External Companies Deals 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: Deals
description: Operations related to deals.
paths:
/v1/groups/{groupId}/{objectType}:
get:
security:
- bearerApiKeyAuth: []
operationId: listDeals
summary: List deals
description: Retrieve a list of deals in the workspace.
tags:
- Deals
parameters:
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The ID of the group the deals belong to. Can be retrieved from the [List groups](/api-reference/groups/list-groups) endpoint.
example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
name: groupId
in: path
- schema:
type: string
maxLength: 500
required: true
description: The name of a deal custom field that can be retrieved from the [List group custom fields](/api-reference/groups/list-group-custom-fields) endpoint.
example: Deals
name: objectType
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
- 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 deals in the workspace.
links:
updateDeal:
operationId: updateDeal
parameters:
dealId: $response.body#/data/items/0/id
groupId: $request.path.groupId
entityType: $request.path.entityType
description: The ids returned by the `GET /v1/groups/:groupId/:objectType` operation can be used as an input to the `PATCH /v1/groups/:groupId/:objectType/:dealId` operation to update a deal.
getDeal:
operationId: getDeal
parameters:
dealId: $response.body#/data/items/0/id
groupId: $request.path.groupId
entityType: $request.path.entityType
description: The ids returned by the `GET /v1/groups/:groupId/:objectType` operation can be used as an input to the `GET /v1/groups/:groupId/:objectType/:dealId` operation to retrieve a deal.
deleteDeal:
operationId: deleteDeal
parameters:
dealId: $response.body#/data/items/0/id
groupId: $request.path.groupId
entityType: $request.path.entityType
description: The ids returned by the `GET /v1/groups/:groupId/:objectType` operation can be used as an input to the `DELETE /v1/groups/:groupId/:objectType/:dealId` operation to delete a deal.
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/Deal'
pagination:
type: object
properties:
nextLink:
type: string
required:
- items
- pagination
example:
items:
- 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
pagination:
nextLink: https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
items:
- 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
pagination:
nextLink: https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals?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: createDeal
summary: Create a deal
description: Create a new deal in the workspace.
tags:
- Deals
parameters:
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The ID of the group the deals belong to. Can be retrieved from the [List groups](/api-reference/groups/list-groups) endpoint.
example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
name: groupId
in: path
- schema:
type: string
maxLength: 500
required: true
description: The name of a deal custom field that can be retrieved from the [List group custom fields](/api-reference/groups/list-group-custom-fields) endpoint.
example: Deals
name: objectType
in: path
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 1000
description: The name of the deal.
example: Project Alpha
companies:
type: array
items:
type: object
properties:
id:
type: string
minLength: 40
maxLength: 40
required:
- id
additionalProperties: false
maxItems: 20
description: The companies associated with the deal.
example:
- id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
people:
type: array
items:
type: object
properties:
id:
type: string
minLength: 40
maxLength: 40
required:
- id
additionalProperties: false
maxItems: 20
description: The people associated with the deal.
example:
- id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
customFieldValues:
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'
description: "The custom field values associated with the deal. The format is the following:\n```json\n{\n \"<customFieldName>\": \"<customFieldValue>\"\n}\n```\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- `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\nPassing a `null` value or an empty array will unset the custom field value."
properties: {}
example:
Status: Active
Deal value: '42000'
Close date: '2021-01-01'
Assignee:
- id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
- email: jane@example.com
additionalProperties: false
responses:
'200':
description: The deal created in the workspace.
links:
updateDeal:
operationId: updateDeal
parameters:
dealId: $response.body#/data/id
groupId: $request.path.groupId
entityType: $request.path.entityType
description: The id returned by the `POST /v1/groups/:groupId/:objectType` operation can be used as an input to the `PATCH /v1/groups/:groupId/:objectType/:dealId` operation to update the deal.
getDeal:
operationId: getDeal
parameters:
dealId: $response.body#/data/id
groupId: $request.path.groupId
entityType: $request.path.entityType
description: The id returned by the `POST /v1/groups/:groupId/:objectType` operation can be used as an input to the `GET /v1/groups/:groupId/:objectType/:dealId` operation to retrieve the deal.
deleteDeal:
operationId: deleteDeal
parameters:
dealId: $response.body#/data/id
groupId: $request.path.groupId
entityType: $request.path.entityType
description: The id returned by the `POST /v1/groups/:groupId/:objectType` operation can be used as an input to the `DELETE /v1/groups/:groupId/:objectType/:dealId` operation to delete the deal.
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/Deal'
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
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
'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}/{objectType}/{objectId}:
get:
security:
- bearerApiKeyAuth: []
operationId: getDeal
summary: Get a deal
description: Retrieve an existing deal in the workspace.
tags:
- Deals
parameters:
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The ID of the group the deals belong to. Can be retrieved from the [List groups](/api-reference/groups/list-groups) endpoint.
example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
name: groupId
in: path
- schema:
type: string
maxLength: 500
required: true
description: The name of a deal custom field that can be retrieved from the [List group custom fields](/api-reference/groups/list-group-custom-fields) endpoint.
example: Deals
name: objectType
in: path
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The ID of the deal to retrieve.
name: objectId
in: path
responses:
'200':
description: The retrieved person 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/Deal'
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
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
'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'
patch:
security:
- bearerApiKeyAuth: []
operationId: updateDeal
summary: Update a deal
description: Update an existing deal in the workspace.
tags:
- Deals
parameters:
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The ID of the group the deals belong to. Can be retrieved from the [List groups](/api-reference/groups/list-groups) endpoint.
example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
name: groupId
in: path
- schema:
type: string
maxLength: 500
required: true
description: The name of a deal custom field that can be retrieved from the [List group custom fields](/api-reference/groups/list-group-custom-fields) endpoint.
example: Deals
name: objectType
in: path
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The ID of the deal to update.
name: objectId
in: path
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 1000
description: The name of the deal.
example: Project Alpha
companies:
type: array
items:
type: object
properties:
id:
type: string
minLength: 40
maxLength: 40
required:
- id
additionalProperties: false
maxItems: 20
description: The companies associated with the deal.
example:
- id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
people:
type: array
items:
type: object
properties:
id:
type: string
minLength: 40
maxLength: 40
required:
- id
additionalProperties: false
maxItems: 20
description: The people associated with the deal.
example:
- id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
customFieldValues:
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'
description: "The custom field values associated with the deal. The format is the following:\n```json\n{\n \"<customFieldName>\": \"<customFieldValue>\"\n}\n```\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- `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\nPassing a `null` value or an empty array will unset the custom field value."
properties: {}
example:
Status: Active
Deal value: '42000'
Close date: '2021-01-01'
Assignee:
- id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
- email: jane@example.com
additionalProperties: false
responses:
'200':
description: The updated deal 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/Deal'
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
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'
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/folk/refs/heads/main/openapi/folk-deals-api-openapi.yml