Folk · Schema
Folk API Schemas
JSON Schema definitions for the Folk REST API resources
CRMContactsPipelinesSalesRelationshipsNotesDealsWebhooks
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Folk API Schemas",
"description": "JSON Schema definitions for the Folk REST API resources",
"definitions": {
"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."
},
"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": "[email protected]"
}
},
"InteractionMetadata": {
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"approximateCount": {
"type": "integer",
"minimum": 0,
"description": "The approximate number of interactions between the current user and the contact.",
"example": 21
},
"lastInteractedAt": {
"type": "string",
"format": "date-time",
"description": "The last interaction date between the current user and the contact.",
"example": "2025-05-01T00:00:00Z",
"nullable": true
}
},
"required": [
"approximateCount",
"lastInteractedAt"
]
},
"workspace": {
"type": "object",
"properties": {
"approximateCount": {
"type": "integer",
"minimum": 0,
"description": "The approximate number of interactions of your workspace with the contact.",
"example": 42
},
"lastInteractedAt": {
"type": "string",
"format": "date-time",
"description": "The last interaction date of your workspace with the contact.",
"example": "2025-05-01T00:00:00Z",
"nullable": true
},
"lastInteractedBy": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
},
"description": "List of users in your workspace who last interacted with the contact.",
"example": [
{
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "[email protected]"
}
]
}
},
"required": [
"approximateCount",
"lastInteractedAt",
"lastInteractedBy"
]
}
},
"required": [
"user",
"workspace"
],
"description": "Metadata about interactions with the user and workspace.",
"example": {
"user": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z"
},
"workspace": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z",
"lastInteractedBy": [
{
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "[email protected]"
}
]
}
}
},
"Person": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"firstName": {
"type": "string",
"description": "The first name of the person.",
"example": "John"
},
"lastName": {
"type": "string",
"description": "The last name of the person.",
"example": "Doe"
},
"fullName": {
"type": "string",
"description": "The full name of the person.",
"example": "John Doe"
},
"description": {
"type": "string",
"description": "A short description of the person.",
"example": "A brief description of the person."
},
"birthday": {
"type": "string",
"minLength": 10,
"maxLength": 10,
"format": "date",
"description": "The birthday of the person, in ISO format.",
"example": "1990-01-01",
"nullable": true
},
"jobTitle": {
"type": "string",
"description": "The job title of the person.",
"example": "Software Engineer"
},
"createdAt": {
"type": "string",
"minLength": 20,
"maxLength": 40,
"description": "The date and time the person was created, in ISO format.",
"example": "2021-01-01T00:00:00.000Z",
"nullable": true
},
"createdBy": {
"$ref": "#/components/schemas/User"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"description": "The groups associated with the person.",
"example": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
"name": "Engineering"
}
]
},
"companies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The id of the company.",
"example": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
},
"name": {
"type": "string",
"description": "The name of the company.",
"example": "Tech Corp"
}
},
"required": [
"id",
"name"
]
},
"description": "The companies associated with the person. The first company in the list is the person's primary company.",
"example": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
"name": "Tech Corp"
}
]
},
"addresses": {
"type": "array",
"items": {
"type": "string",
"description": "An address associated with the person. The first address in the list is the person's primary address.",
"example": "123 Main St, Springfield, USA"
}
},
"emails": {
"type": "array",
"items": {
"type": "string",
"description": "An email address associated with the person. The first email address in the list is the person's primary email address.",
"example": "[email protected]"
}
},
"phones": {
"type": "array",
"items": {
"type": "string",
"description": "A phone number associated with the person. The first phone number in the list is the person's primary phone number.",
"example": "+1234567890"
}
},
"urls": {
"type": "array",
"items": {
"type": "string",
"description": "A URL associated with the person. The first URL in the list is the person's primary URL.",
"example": "https://example.com"
}
},
"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": "[email protected]"
},
{
"id": "usr_a95a1b90-8e88-4855-bc29-d47b8e2704e1",
"fullName": "John Doe",
"email": "[email protected]"
}
]
},
{
"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"
}
]
}
}
},
"interactionMetadata": {
"$ref": "#/components/schemas/InteractionMetadata"
},
"strongestConnection": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/User"
},
"description": "For each group the person is in, the workspace member with the strongest connection to the person. If the person has no strongest connection, this will be an empty object. Only the groups for which the person has a strongest connection will be included.",
"example": {
"grp_92346499-30bf-4278-ae8e-4aa3ae2ace2c": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "[email protected]"
}
}
}
},
"required": [
"id",
"firstName",
"lastName",
"fullName",
"description",
"birthday",
"jobTitle",
"createdAt",
"createdBy",
"groups",
"companies",
"addresses",
"emails",
"phones",
"urls",
"customFieldValues",
"interactionMetadata"
],
"description": "A person in the workspace.",
"example": {
"id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"description": "John Doe is a software engineer at Tech Corp.",
"birthday": "1980-06-15",
"jobTitle": "Software Engineer",
"createdAt": "2021-01-01T00:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "[email protected]"
},
"groups": [
{
"id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
"name": "Engineering"
}
],
"companies": [
{
"id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
"name": "Tech Corp"
}
],
"addresses": [
"123 Main St, Springfield, USA",
"456 Main St, Springfield, USA"
],
"emails": [
"[email protected]",
"[email protected]"
],
"phones": [
"+1234567890",
"+0987654321"
],
"urls": [
"https://example.com"
],
"customFieldValues": {
"grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
"Status": "Active",
"Programming languages": [
"Javascript",
"Python"
],
"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": {
"Favorite color": "Blue",
"Favorite number": "42",
"Assignee": [
{
"id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
"fullName": "Jane Doe",
"email": "[email protected]"
}
]
}
},
"interactionMetadata": {
"user": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z"
},
"workspace": {
"approximateCount": 21,
"lastInteractedAt": "2025-05-01T00:00:00Z",
"lastInteractedBy": [
{
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "[email protected]"
}
]
}
},
"strongestConnection": {
"grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "[email protected]"
}
}
}
},
"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",
"description": "The amount in USD of funding raised by the company.",
"example": "5000000",
"nullable": true
},
"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",
"description": "The industry the company operates in.",
"example": "Technology",
"nullable": true
},
"foundationYear": {
"type": "string",
"description": "The foundation year of the company, in YYYY format.",
"example": "1990",
"nullable": true
},
"employeeRange": {
"type": "string",
"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",
"nullable": true
},
"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": "[email protected]"
}
},
"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",
"minLength": 20,
"maxLength": 40,
"description": "The date and time the company was created, in ISO format.",
"example": "2021-01-01T00:00:00.000Z",
"nullable": true
},
"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": "[email protected]"
},
{
"id": "usr_a95a1b90-8e88-4855-bc29-d47b8e2704e1",
"fullName": "John Doe",
"email": "[email protected]"
}
]
},
{
"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": [
"[email protected]",
"[email protected]"
],
"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": "[email protected]"
},
"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": "[email protected]"
}
]
}
}
}
},
"Deal": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"description": "The name of the deal.",
"example": "Project Alpha"
},
"companies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"description": "The name of the company.",
"example": "Tech Corp"
}
},
"required": [
"id",
"name"
]
}
},
"people": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"fullName": {
"type": "string",
"description": "The name of the person.",
"example": "John Doe"
}
},
"required": [
"id",
"fullName"
]
}
},
"createdAt": {
"type": "string",
"minLength": 20,
"maxLength": 40,
"description": "The date and time the deal was created, in ISO format.",
"example": "2021-01-01T00:00:00.000Z",
"nullable": true
},
"createdBy": {
"$ref": "#/components/schemas/User"
},
"customFieldValues": {
"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": "[email protected]"
},
{
"id": "usr_a95a1b90-8e88-4855-bc29-d47b8e2704e1",
"fullName": "John Doe",
"email": "[email protected]"
}
]
},
{
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"fullName": {
"type": "st
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/folk/refs/heads/main/json-schema/folk-schemas.json