{ "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" } }, "openapi": "3.1.0", "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." }, { "name": "Deals", "description": "Operations related to deals." }, { "name": "Groups", "description": "Operations related to groups." }, { "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." } ], "components": { "securitySchemes": { "bearerApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "API key for authentication" } }, "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." }, "Retry-After": { "schema": { "type": "integer", "example": 60 }, "description": "The number of seconds to wait before making a new request after hitting the rate limit." } }, "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" }, "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" }, "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" }, "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" }, "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" } } } } }, "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" } } } } }, "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" } } } } } }, "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" } } } } } }, "schemas": { "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": "john.doe@example.com" } }, "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", "null" ], "format": "date-time", "description": "The last interaction date between the current user and the contact.", "example": "2025-05-01T00:00:00Z" } }, "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", "null" ], "format": "date-time", "description": "The last interaction date of your workspace with the contact.", "example": "2025-05-01T00:00:00Z" }, "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": "john.doe@example.com" } ] } }, "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": "john.doe@example.com" } ] } } }, "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", "null" ], "minLength": 10, "maxLength": 10, "format": "date", "description": "The birthday of the person, in ISO format. Deleted with null or empty string.", "example": "1990-01-01" }, "gender": { "type": [ "string", "null" ], "enum": [ "Male", "Female", "Unknown", "Other" ], "description": "The gender of the person. Authorized values are \"Female\", \"Male\", \"Unknown\", \"Other\" or null to delete it.", "example": "Unknown" }, "jobTitle": { "type": "string", "description": "The job title of the person.", "example": "Software Engineer" }, "createdAt": { "type": [ "string", "null" ], "minLength": 20, "maxLength": 40, "description": "The date and time the person was created, in ISO format.", "example": "2021-01-01T00:00:00.000Z" }, "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": "john@example.com" } }, "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": "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" } ] } } }, "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": "john.doe@example.com" } } } }, "required": [ "id", "firstName", "lastName", "fullName", "description", "birthday", "gender", "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", "gender": "Female", "jobTitle": "Software Engineer", "createdAt": "2021-01-01T00:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "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": [ "john@example.com", "john@techcorp.com" ], "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": "jane@example.com" } ] } }, "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": "john.doe@example.com" } ] } }, "strongestConnection": { "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" } } } }, "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" } ] } } } }, "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", "null" ], "minLength": 20, "maxLength": 40, "description": "The date and time the deal was created, in ISO format.", "example": "2021-01-01T00:00:00.000Z" }, "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": "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", "companies", "people", "createdAt", "createdBy", "customFieldValues" ], "description": "A deal in the workspace.", "example": { "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" } ] } } }, "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" } }, "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" } ] } }, "CurrentUser": { "type": "object", "properties": { "id": { "type": "string" }, "fullName": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "fullName", "email" ], "description": "The current workspace user.", "example": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" } }, "Note": { "type": "object", "properties": { "id": { "type": "string" }, "entity": { "type": "object", "properties": { "id": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The ID of the entity connected to the note.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "entityType": { "type": "string", "enum": [ "person", "company", "object" ], "description": "The type of the entity connected to the note. Can be `person`, `company` or `object`.", "example": "person" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The full name of the entity connected to the note.", "example": "John Doe" } }, "required": [ "id", "entityType", "fullName" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "The content of the note. Can be in plain text or in markdown format.", "example": "This is a note about **John Doe**" }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the note.\n\n- `public`: The note is visible to all users in the workspace.\n- `private`: The note is visible only to the current user.\n " }, "author": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ], "description": "The type of the author of the note, it can be a user or a folk assistant.", "example": "user" }, "id": { "type": "string", "description": "The ID of the author of the note.", "example": "usr_55175e81-9a52-4ac3-930e-82792c23499b" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The full name of the author of the note.", "example": "John Doe" }, "email": { "type": "string", "maxLength": 254, "format": "email", "description": "The email of the author of the note.", "example": "john.doe@example.com" }, "deleted": { "type": "boolean", "enum": [ false ], "description": "Whether the author has been deleted and does not exist anymore.", "example": false } }, "required": [ "type", "id", "fullName", "email", "deleted" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "assistant" ], "description": "The type of the author of the note, it can be a user or a folk assistant.", "example": "assistant" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The name of the folk assistant that created the note.", "example": "Research assistant" } }, "required": [ "type", "fullName" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ], "description": "The type of the author of the note, it can be a user or a folk assistant.", "example": "user" }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Whether the author has been deleted and does not exist anymore.", "example": true } }, "required": [ "type", "id", "deleted" ] } ] }, "createdAt": { "type": [ "string", "null" ], "minLength": 20, "maxLength": 40, "description": "The date and time the note was created, in ISO format.", "example": "2021-01-01T00:00:00.000Z" }, "parentNote": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Whether the parent note has been deleted and does not exist anymore.", "example": true } }, "required": [ "id", "deleted" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "entity": { "type": "object", "properties": { "id": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The ID of the entity connected to the note.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "entityType": { "type": "string", "enum": [ "person", "company", "object" ], "description": "The type of the entity connected to the note. Can be `person`, `company` or `object`.", "example": "person" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The full name of the entity connected to the note.", "example": "John Doe" } }, "required": [ "id", "entityType", "fullName" ] }, "content": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100000, "description": "The content of the parent note. If the parent note is not visible to the current user, this field will be null.", "example": "This is a parent note about John Doe" }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the note.\n\n- `public`: The note is visible to all users in the workspace.\n- `private`: The note is visible only to the current user.\n " }, "author": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ], "description": "The type of the author of the note, it can be a user or a folk assistant.", "example": "user" }, "id": { "type": "string", "description": "The ID of the author of the note.", "example": "usr_55175e81-9a52-4ac3-930e-82792c23499b" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The full name of the author of the note.", "example": "John Doe" }, "email": { "type": "string", "maxLength": 254, "format": "email", "description": "The email of the author of the note.", "example": "john.doe@example.com" }, "deleted": { "type": "boolean", "enum": [ false ], "description": "Whether the author has been deleted and does not exist anymore.", "example": false } }, "required": [ "type", "id", "fullName", "email", "deleted" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "assistant" ], "description": "The type of the author of the note, it can be a user or a folk assistant.", "example": "assistant" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The name of the folk assistant that created the note.", "example": "Research assistant" } }, "required": [ "type", "fullName" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ], "description": "The type of the author of the note, it can be a user or a folk assistant.", "example": "user" }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Whether the author has been deleted and does not exist anymore.", "example": true } }, "required": [ "type", "id", "deleted" ] } ] }, "createdAt": { "type": [ "string", "null" ], "minLength": 20, "maxLength": 40, "description": "The date and time the parent note was created, in ISO format.", "example": "2021-01-01T00:00:00.000Z" }, "deleted": { "type": "boolean", "enum": [ false ], "description": "Whether the parent note has been deleted and does not exist anymore.", "example": false } }, "required": [ "id", "entity", "content", "visibility", "author", "createdAt", "deleted" ] }, { "type": "null" } ], "description": "The parent note, if this note is a reply to another note.", "example": { "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "content": "This is a parent note about John Doe", "visibility": "public", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "deleted": false } } }, "required": [ "id", "entity", "content", "visibility", "author", "createdAt", "parentNote" ], "description": "A note linked to an entity.", "example": { "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "visibility": "public", "content": "This is a note about John Doe", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "parentNote": { "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "content": "This is a parent note about John Doe", "visibility": "public", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "deleted": false } } }, "Reminder": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 255 }, "entity": { "type": "object", "properties": { "id": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The ID of the entity connected to the reminder.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "entityType": { "type": "string", "enum": [ "person", "company", "object" ], "description": "The type of the entity connected to the reminder. Can be `person`, `company` or `object`.", "example": "person" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The full name of the entity connected to the reminder.", "example": "John Doe" } }, "required": [ "id", "entityType", "fullName" ] }, "recurrenceRule": { "type": "string", "description": "The recurrence rule of the reminder. The recurrence rule is a string that follows the iCalendar format specified in [RFC 5545](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html).", "example": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1" }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the reminder.\n\n- `public`: The reminder is visible to all users in the workspace.\n- `private`: The reminder is visible only to the current user.\n " }, "assignedUsers": { "type": "array", "items": { "$ref": "#/components/schemas/User" }, "description": "A list of workspace users to be notified when the reminder is triggered. For private reminders, only the current user is notified.", "example": [ { "id": "usr_a45c30d8-19fc-4939-94c7-17dc5e46f476", "fullName": "John Doe", "email": "john.doe@example.com" } ] }, "nextTriggerTime": { "type": [ "string", "null" ], "format": "date-time", "description": "The next trigger time of the reminder.", "example": "2025-07-17T09:00:00.000Z" }, "lastTriggerTime": { "type": [ "string", "null" ], "format": "date-time", "description": "The last trigger time of the reminder.", "example": "2025-05-17T09:00:00.000Z" }, "createdBy": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "description": "The user who created the reminder." } ] }, "createdAt": { "type": [ "string", "null" ], "minLength": 20, "maxLength": 40, "description": "The date and time the reminder was created, in ISO format.", "example": "2021-01-01T00:00:00.000Z" } }, "required": [ "id", "name", "entity", "recurrenceRule", "visibility", "assignedUsers", "nextTriggerTime", "lastTriggerTime", "createdBy", "createdAt" ], "description": "A reminder linked to an entity.", "example": { "id": "rmd_91118b73-5a75-480b-b8e3-a33671c35cdc", "name": "Reminder on John Doe", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1", "visibility": "public", "assignedUsers": [ { "id": "usr_a45c30d8-19fc-4939-94c7-17dc5e46f476", "fullName": "John Doe", "email": "john.doe@example.com" } ], "nextTriggerTime": "2025-07-17T09:00:00.000Z", "lastTriggerTime": "2025-05-17T09:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "createdAt": "2021-01-01T00:00:00.000Z" } }, "TSK_Task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "description": "The title of the task.", "example": "Follow up with John Doe" }, "description": { "type": [ "string", "null" ], "description": "The description of the task, in markdown format.", "example": "Discuss the Q3 proposal." }, "entity": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the entity connected to the task.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "entityType": { "type": "string", "enum": [ "person", "company", "object" ], "description": "The type of entity connected to the task.", "example": "person" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The full name of the entity.", "example": "John Doe" } }, "required": [ "id", "entityType", "fullName" ] }, "recurrenceRule": { "type": [ "string", "null" ], "description": "The recurrence rule of the task (RFC 5545 rrule string), or null if non-recurring." }, "dueAt": { "type": "string", "minLength": 10, "maxLength": 10, "format": "date", "description": "The due date of the task, in YYYY-MM-DD format.", "example": "2025-07-17" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The date and time the task was completed, or null if not yet completed.", "example": "2025-07-17T09:00:00.000Z" }, "isPublic": { "type": "boolean", "description": "Whether the task is visible to all workspace members.", "example": true }, "assignedUsers": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "createdBy": { "$ref": "#/components/schemas/User" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "title", "description", "entity", "recurrenceRule", "dueAt", "completedAt", "isPublic", "assignedUsers", "createdBy", "createdAt", "updatedAt" ], "example": { "id": "tsk_91118b73-5a75-480b-b8e3-a33671c35cdc", "title": "Follow up with John Doe", "description": "Discuss the Q3 proposal.", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "dueAt": "2025-07-17", "completedAt": null, "recurrenceRule": null, "isPublic": true, "assignedUsers": [ { "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com" } ], "createdBy": { "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com" }, "createdAt": "2025-07-17T09:00:00.000Z", "updatedAt": "2025-07-17T09:00:00.000Z" } }, "LoggedInteraction": { "type": "object", "properties": { "id": { "type": "string" }, "interactionType": { "type": "string", "enum": [ "logged" ], "description": "The interaction is a manually logged interaction.", "example": "logged" }, "from": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ], "description": "The interaction was logged by a workspace member.", "example": "user" }, "value": { "type": "string" }, "name": { "type": "string", "description": "The display name of the user.", "example": "John Doe" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sender" ], "description": "The interaction was logged on behalf of an email sender, such as a campaign message.", "example": "sender" }, "name": { "type": "string", "description": "The display name of the sender.", "example": "Jane Doe" }, "value": { "type": "string", "description": "The email address of the sender.", "example": "jane@example.com" } }, "required": [ "type", "name", "value" ] } ], "description": "Who logged the interaction. Can be a workspace user or an email sender." }, "to": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "person" ] }, { "type": "string", "enum": [ "company" ] } ], "description": "The type of the entity the interaction is linked to.", "example": "person" }, "value": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The ID of the person or company the interaction is linked to.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "name": { "type": "string", "description": "The full name of the linked entity.", "example": "John Doe" } }, "required": [ "type", "value" ], "description": "The entity the interaction is linked to." }, "entity": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "person", "company" ], "description": "The type of the entity connected to the interaction. Can be `person` or `company`.", "example": "person" }, "id": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The ID of the entity connected to the interaction.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "fullName": { "type": "string", "description": "The full name of the entity connected to the interaction.", "example": "John Doe" } }, "required": [ "entityType", "id", "fullName" ], "description": "The entity connected to the interaction." }, "dateTime": { "type": "string", "format": "date-time", "description": "The date and time of the interaction.", "example": "2025-07-17T09:00:00.000Z" }, "title": { "type": "string", "description": "The title of the interaction.", "example": "Coffee with John Doe" }, "content": { "type": "string", "description": "The multi-line content of the interaction.", "example": "Had a coffee with John Doe\nDiscussed the new project." }, "privacyLevel": { "type": "string", "enum": [ "sharedFull" ], "description": "Logged interactions always expose their content to authorized users.", "example": "sharedFull" }, "type": { "anyOf": [ { "type": "string", "maxLength": 50, "format": "emoji", "description": "An emoji representing the interaction type.", "example": "☕️" }, { "type": "string", "enum": [ "call", "meeting", "message", "coffee", "lunch", "event", "drink" ], "description": "A predefined interaction type.", "example": "coffee" }, { "type": "string", "enum": [ "whatsapp", "twitter", "linkedin", "hangout", "skype", "slack", "iMessage", "fbMessenger", "signal", "discord", "wechat", "telegram", "viber" ], "description": "A messaging app used for the interaction.", "example": "slack" }, { "type": "string", "enum": [ "campaignMessage" ], "description": "A campaign message sent via folk.", "example": "campaignMessage" } ], "description": "Deprecated. Use `activityType` instead.", "deprecated": true, "example": "coffee" }, "activityType": { "anyOf": [ { "type": "string", "maxLength": 50, "format": "emoji", "description": "An emoji representing the interaction type.", "example": "☕️" }, { "type": "string", "enum": [ "call", "meeting", "message", "coffee", "lunch", "event", "drink" ], "description": "A predefined interaction type.", "example": "coffee" }, { "type": "string", "enum": [ "whatsapp", "twitter", "linkedin", "hangout", "skype", "slack", "iMessage", "fbMessenger", "signal", "discord", "wechat", "telegram", "viber" ], "description": "A messaging app used for the interaction.", "example": "slack" }, { "type": "string", "enum": [ "campaignMessage" ], "description": "A campaign message sent via folk.", "example": "campaignMessage" } ], "description": "The logged activity type. Can be a predefined activity, a messaging app, or an emoji.", "example": "coffee" } }, "required": [ "id", "interactionType", "from", "to", "entity", "dateTime", "title", "content", "privacyLevel", "type", "activityType" ], "description": "A manually logged interaction linked to an entity.", "example": { "id": "lit_b049db09-c03d-4f32-96d6-d314760add5d", "interactionType": "logged", "from": { "type": "user", "value": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "name": "John Doe" }, "to": { "type": "person", "value": "per_55175e81-9a52-4ac3-930e-82792c23499b", "name": "John Doe" }, "title": "Coffee with John Doe", "content": "Had a coffee with John Doe\nDiscussed the new project.", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "dateTime": "2025-07-17T09:00:00.000Z", "privacyLevel": "sharedFull", "type": "coffee", "activityType": "coffee" } }, "EmailMessageInteraction": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "entity": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "person", "company" ], "description": "The type of the entity connected to the interaction. Can be `person` or `company`.", "example": "person" }, "id": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The ID of the entity connected to the interaction.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "fullName": { "type": "string", "description": "The full name of the entity connected to the interaction.", "example": "John Doe" } }, "required": [ "entityType", "id", "fullName" ], "description": "The entity connected to the interaction." }, "dateTime": { "type": "string", "format": "date-time", "description": "The date and time of the interaction.", "example": "2025-07-17T09:00:00.000Z" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "A link to open the interaction in the original source, when available.", "example": "https://mail.google.com/mail/u/0/#inbox/abc123" }, "privacyLevel": { "type": "string", "enum": [ "sharedFull", "subjectOnly", "sensitive", "internal" ], "description": "Interaction privacy level:\n- `**sharedFull` means the interaction content is fully visible to every workspace member.\n- `**subjectOnly` means the interacton content is hidden for other workspace members.\n- `**sensitve`/`internal` means the interaction is visible only to the workspace members involved in the conversation.\nFor more information about interaction privacy, see our [help center article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)\n", "example": "sharedFull" }, "interactionType": { "type": "string", "enum": [ "email" ], "description": "The interaction is an imported email message.", "example": "email" }, "from": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "description": "The email address of the participant.", "example": "jane@example.com" }, "name": { "type": "string", "description": "The display name of the participant.", "example": "Jane Doe" } }, "required": [ "type", "value" ] }, "to": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "description": "The email address of the participant.", "example": "jane@example.com" }, "name": { "type": "string", "description": "The display name of the participant.", "example": "Jane Doe" } }, "required": [ "type", "value" ] }, "description": "The recipients of the email." }, "content": { "type": "object", "properties": { "subject": { "type": "string", "description": "The subject of the email or calendar event.", "example": "Project kickoff" }, "snippet": { "type": "string", "description": "A short preview of the interaction content. Omitted when privacy rules restrict content.", "example": "Looking forward to discussing the roadmap." }, "location": { "type": "string", "description": "The location of the calendar event, when available.", "example": "Conference room A" }, "body": { "type": "string", "description": "The full body of the email or calendar event. Only returned by the get interaction endpoint.", "example": "Hi team,\n\nLooking forward to our kickoff meeting." } }, "required": [ "subject" ] } }, "required": [ "id", "entity", "dateTime", "url", "privacyLevel", "interactionType", "from", "to", "content" ], "description": "An imported email message linked to an entity.", "example": { "id": "b049db09-c03d-4f32-96d6-d314760add5d@gmail.com", "interactionType": "email", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "dateTime": "2025-07-17T09:00:00.000Z", "url": "https://mail.google.com/mail/u/0/#inbox/abc123", "privacyLevel": "sharedFull", "from": { "type": "email", "value": "jane@example.com", "name": "Jane Doe" }, "to": [ { "type": "email", "value": "john@example.com", "name": "John Doe" } ], "content": { "subject": "Project kickoff", "snippet": "Looking forward to discussing the roadmap." } } }, "CalendarEventInteraction": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "entity": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "person", "company" ], "description": "The type of the entity connected to the interaction. Can be `person` or `company`.", "example": "person" }, "id": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The ID of the entity connected to the interaction.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "fullName": { "type": "string", "description": "The full name of the entity connected to the interaction.", "example": "John Doe" } }, "required": [ "entityType", "id", "fullName" ], "description": "The entity connected to the interaction." }, "dateTime": { "type": "string", "format": "date-time", "description": "The date and time of the interaction.", "example": "2025-07-17T09:00:00.000Z" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "A link to open the interaction in the original source, when available.", "example": "https://mail.google.com/mail/u/0/#inbox/abc123" }, "privacyLevel": { "type": "string", "enum": [ "sharedFull", "subjectOnly", "sensitive", "internal" ], "description": "Interaction privacy level:\n- `**sharedFull` means the interaction content is fully visible to every workspace member.\n- `**subjectOnly` means the interacton content is hidden for other workspace members.\n- `**sensitve`/`internal` means the interaction is visible only to the workspace members involved in the conversation.\nFor more information about interaction privacy, see our [help center article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)\n", "example": "sharedFull" }, "interactionType": { "type": "string", "enum": [ "calendar" ], "description": "The interaction is an imported calendar event.", "example": "calendar" }, "from": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "description": "The email address of the participant.", "example": "jane@example.com" }, "name": { "type": "string", "description": "The display name of the participant.", "example": "Jane Doe" } }, "required": [ "type", "value" ] }, "to": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "description": "The email address of the participant.", "example": "jane@example.com" }, "name": { "type": "string", "description": "The display name of the participant.", "example": "Jane Doe" } }, "required": [ "type", "value" ] }, "description": "The attendees of the calendar event." }, "content": { "type": "object", "properties": { "subject": { "type": "string", "description": "The subject of the email or calendar event.", "example": "Project kickoff" }, "snippet": { "type": "string", "description": "A short preview of the interaction content. Omitted when privacy rules restrict content.", "example": "Looking forward to discussing the roadmap." }, "location": { "type": "string", "description": "The location of the calendar event, when available.", "example": "Conference room A" }, "body": { "type": "string", "description": "The full body of the email or calendar event. Only returned by the get interaction endpoint.", "example": "Hi team,\n\nLooking forward to our kickoff meeting." } }, "required": [ "subject" ] } }, "required": [ "id", "entity", "dateTime", "url", "privacyLevel", "interactionType", "from", "to", "content" ], "description": "An imported calendar event linked to an entity.", "example": { "id": "c149db09-c03d-4f32-96d6-d314760add5e@gmail.com", "interactionType": "calendar", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "dateTime": "2025-07-18T14:00:00.000Z", "url": "https://calendar.google.com/event?eid=abc123", "privacyLevel": "sharedFull", "from": { "type": "email", "value": "jane@example.com", "name": "Jane Doe" }, "to": [ { "type": "email", "value": "john@example.com", "name": "John Doe" } ], "content": { "subject": "Weekly sync", "location": "Conference room A" } } }, "WhatsappMessageInteraction": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "entity": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "person", "company" ], "description": "The type of the entity connected to the interaction. Can be `person` or `company`.", "example": "person" }, "id": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The ID of the entity connected to the interaction.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b" }, "fullName": { "type": "string", "description": "The full name of the entity connected to the interaction.", "example": "John Doe" } }, "required": [ "entityType", "id", "fullName" ], "description": "The entity connected to the interaction." }, "dateTime": { "type": "string", "format": "date-time", "description": "The date and time of the interaction.", "example": "2025-07-17T09:00:00.000Z" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "A link to open the interaction in the original source, when available.", "example": "https://mail.google.com/mail/u/0/#inbox/abc123" }, "privacyLevel": { "type": "string", "enum": [ "sharedFull", "subjectOnly", "sensitive", "internal" ], "description": "Interaction privacy level:\n- `**sharedFull` means the interaction content is fully visible to every workspace member.\n- `**subjectOnly` means the interacton content is hidden for other workspace members.\n- `**sensitve`/`internal` means the interaction is visible only to the workspace members involved in the conversation.\nFor more information about interaction privacy, see our [help center article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)\n", "example": "sharedFull" }, "interactionType": { "type": "string", "enum": [ "whatsapp" ], "description": "The interaction is an imported WhatsApp message.", "example": "whatsapp" }, "from": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "description": "The phone number of the participant.", "example": "+14155552671" }, "name": { "type": "string", "description": "The display name of the participant.", "example": "Jane Doe" } }, "required": [ "type", "value" ] }, "to": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "description": "The phone number of the participant.", "example": "+14155552671" }, "name": { "type": "string", "description": "The display name of the participant.", "example": "Jane Doe" } }, "required": [ "type", "value" ] }, "description": "The recipients of the WhatsApp message." }, "content": { "type": "object", "properties": { "text": { "type": "string", "description": "The message text. Omitted when privacy rules restrict content.", "example": "Are we still on for tomorrow?" }, "context": { "type": "string", "description": "Additional context around the message. Omitted when privacy rules restrict content.", "example": "" } } } }, "required": [ "id", "entity", "dateTime", "url", "privacyLevel", "interactionType", "from", "to", "content" ], "description": "An imported WhatsApp message linked to an entity.", "example": { "id": "d249db09-c03d-4f32-96d6-d314760add5f@whatsapp.com", "interactionType": "whatsapp", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "dateTime": "2025-07-17T10:30:00.000Z", "url": null, "privacyLevel": "sensitive", "from": { "type": "phone", "value": "+14155552671", "name": "Jane Doe" }, "to": [ { "type": "phone", "value": "+14155559876", "name": "John Doe" } ], "content": { "text": "Are we still on for tomorrow?" } } }, "Interaction": { "anyOf": [ { "$ref": "#/components/schemas/EmailMessageInteraction" }, { "$ref": "#/components/schemas/CalendarEventInteraction" }, { "$ref": "#/components/schemas/WhatsappMessageInteraction" }, { "$ref": "#/components/schemas/LoggedInteraction" } ], "description": "An interaction linked to an entity. Can be imported (email, calendar, WhatsApp) or manually logged.", "example": { "id": "lit_b049db09-c03d-4f32-96d6-d314760add5d", "interactionType": "logged", "from": { "type": "user", "value": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "name": "John Doe" }, "to": { "type": "person", "value": "per_55175e81-9a52-4ac3-930e-82792c23499b", "name": "John Doe" }, "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "dateTime": "2025-07-17T09:00:00.000Z", "privacyLevel": "sharedFull", "title": "Coffee with John Doe", "content": "Had a coffee with John Doe\nDiscussed the new project.", "type": "coffee", "activityType": "coffee" } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 255, "description": "A friendly name for the webhook.", "example": "My app integration" }, "targetUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The URL of the webhook.", "example": "https://my-app.com/webhook" }, "subscribedEvents": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string" }, "filter": { "type": "object", "properties": { "groupId": { "type": "string", "maxLength": 255 }, "objectType": { "type": "string", "maxLength": 255 }, "path": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 3 }, "value": { "type": "string", "maxLength": 255 } }, "default": {} } }, "required": [ "eventType" ] }, "maxItems": 20, "description": "The events the webhook is subscribed to, with optional filters. For more information on how to use filters, see the [create webhook documentation](/api-reference/webhooks/create-a-webhook).", "example": [ { "eventType": "person.created", "filter": {} } ] }, "redactedSigningSecret": { "type": "string", "maxLength": 255, "description": "The signing secret of the webhook.", "example": "whs_fx**********************oVMa" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of the webhook.", "example": "active" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the webhook was created.", "example": "2025-07-17T09:00:00.000Z" } }, "required": [ "id", "name", "targetUrl", "subscribedEvents", "redactedSigningSecret", "status", "createdAt" ], "description": "A webhook listening to events from the workspace and sending them to a URL.", "example": { "id": "wbk_8c18c158-d49e-4ad4-90d4-2b197688bac7", "name": "My app integration", "targetUrl": "https://my-app.com/webhook", "subscribedEvents": [ { "eventType": "person.created", "filter": {} } ], "redactedSigningSecret": "whs_fx**********************oVMa", "status": "active", "createdAt": "2025-07-17T09:00:00.000Z" } }, "WebhookWithSigningSecret": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 255, "description": "A friendly name for the webhook.", "example": "My app integration" }, "targetUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The URL of the webhook.", "example": "https://my-app.com/webhook" }, "subscribedEvents": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string" }, "filter": { "type": "object", "properties": { "groupId": { "type": "string", "maxLength": 255 }, "objectType": { "type": "string", "maxLength": 255 }, "path": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 3 }, "value": { "type": "string", "maxLength": 255 } }, "default": {} } }, "required": [ "eventType" ] }, "maxItems": 20, "description": "The events the webhook is subscribed to, with optional filters. For more information on how to use filters, see the [create webhook documentation](/api-reference/webhooks/create-a-webhook).", "example": [ { "eventType": "person.created", "filter": {} } ] }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of the webhook.", "example": "active" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the webhook was created.", "example": "2025-07-17T09:00:00.000Z" }, "signingSecret": { "type": "string", "maxLength": 255, "description": "The signing secret of the webhook.", "example": "whsec_QWFSUzl1QUVoQW1kdWtpTnJRTUFpbXNlZmxLTg==" } }, "required": [ "id", "name", "targetUrl", "subscribedEvents", "status", "createdAt", "signingSecret" ], "description": "A webhook with a visible signing secret.", "example": { "id": "wbk_8c18c158-d49e-4ad4-90d4-2b197688bac7", "name": "My app integration", "targetUrl": "https://my-app.com/webhook", "subscribedEvents": [ { "eventType": "person.created", "filter": {} } ], "signingSecret": "whsec_QWFSUzl1QUVoQW1kdWtpTnJRTUFpbXNlZmxLTg==", "status": "active", "createdAt": "2025-07-17T09:00:00.000Z" } } }, "parameters": {} }, "paths": { "/v1/people": { "get": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "listPeople", "summary": "List people", "description": "Retrieve a list of people in the workspace.", "tags": [ "People" ], "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": 512 }, "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 people in the workspace.", "links": { "updatePerson": { "operationId": "updatePerson", "parameters": { "personId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/people` operation can be used as an input to the `PATCH /v1/people/:personId` operation to update a person." }, "getPerson": { "operationId": "getPerson", "parameters": { "personId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/people` operation can be used as an input to the `GET /v1/people/:personId` operation to retrieve a person." }, "deletePerson": { "operationId": "deletePerson", "parameters": { "personId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/people` operation can be used as an input to the `DELETE /v1/people/:personId` operation to delete a person." } }, "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/Person" } }, "pagination": { "type": "object", "properties": { "nextLink": { "type": "string" } } } }, "required": [ "items", "pagination" ], "example": { "items": [ { "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", "gender": "Female", "jobTitle": "Software Engineer", "createdAt": "2021-01-01T00:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "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": [ "john@example.com", "john@techcorp.com" ], "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": "jane@example.com" } ] } }, "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": "john.doe@example.com" } ] } }, "strongestConnection": { "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" } } } ], "pagination": { "nextLink": "https://api.folk.app/v1/people?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D" } } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "items": [ { "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", "gender": "Female", "jobTitle": "Software Engineer", "createdAt": "2021-01-01T00:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "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": [ "john@example.com", "john@techcorp.com" ], "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": "jane@example.com" } ] } }, "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": "john.doe@example.com" } ] } }, "strongestConnection": { "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" } } } ], "pagination": { "nextLink": "https://api.folk.app/v1/people?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": [] } ], "x-stability-level": "alpha", "operationId": "createPerson", "summary": "Create a person", "description": "Create a new person in the workspace.", "tags": [ "People" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 500, "description": "The first name of the person.", "example": "John" }, "lastName": { "type": "string", "maxLength": 500, "description": "The last name of the person.", "example": "Doe" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The full name of the person.", "example": "John Doe" }, "description": { "type": "string", "maxLength": 5000, "description": "A short description of the person.", "example": "A brief description of the person." }, "birthday": { "anyOf": [ { "type": "string", "minLength": 10, "maxLength": 10, "format": "date" }, { "type": "string", "enum": [ "" ] }, { "type": "null" }, { "type": "null" } ], "description": "The birthday of the person, in ISO format. Deleted with null or empty string.", "example": "1990-01-01" }, "gender": { "type": [ "string", "null" ], "enum": [ "Male", "Female", "Unknown", "Other" ], "description": "The gender of the person. Authorized values are \"Female\", \"Male\", \"Unknown\", \"Other\" or null to delete it.", "example": "Unknown" }, "jobTitle": { "type": "string", "maxLength": 500, "description": "The job title of the person.", "example": "Software Engineer" }, "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 person to. You must provide group ids.", "example": [ { "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" } ] }, "companies": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 40, "maxLength": 40 } }, "required": [ "id" ], "additionalProperties": false } ] }, "maxItems": 20, "description": "The companies associated with the person. You can either provide a name or an id. If you provide a name, the company will be created if it does not already exist. The first company in the list will be the person's primary company.", "example": [ { "name": "Tech Corp" }, { "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c" } ] }, "addresses": { "type": "array", "items": { "type": "string", "maxLength": 500, "description": "", "example": "" }, "maxItems": 20, "description": "A list of addresses associated with the person. The first address in the list will be the person'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 person. The first email address in the list will be the person'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 person. The first phone number in the list will be the person'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 person. The first URL in the list will be the person'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 person, grouped by group ids. The format is the following:\n```json\n{\n \"\": {\n \"\": \"\"\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", "Programming languages": [ "Javascript", "Python" ], "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": { "Favorite color": "Blue", "Favorite number": 42, "Assignee": [ { "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6" }, { "email": "jane@example.com" } ] } } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The person created in the workspace.", "links": { "updatePerson": { "operationId": "updatePerson", "parameters": { "personId": "$response.body#/data/id" }, "description": "The id returned by the `POST /v1/people` operation can be used as an input to the `PATCH /v1/people/:personId` operation to update the person." }, "getPerson": { "operationId": "getPerson", "parameters": { "personId": "$response.body#/data/id" }, "description": "The id returned by the `POST /v1/people` operation can be used as an input to the `GET /v1/people/:personId` operation to retrieve the person." }, "deletePerson": { "operationId": "deletePerson", "parameters": { "personId": "$response.body#/data/id" }, "description": "The id returned by the `POST /v1/people` operation can be used as an input to the `DELETE /v1/people/:personId` operation to delete the person." } }, "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/Person" }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "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", "gender": "Female", "jobTitle": "Software Engineer", "createdAt": "2021-01-01T00:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "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": [ "john@example.com", "john@techcorp.com" ], "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": "jane@example.com" } ] } }, "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": "john.doe@example.com" } ] } }, "strongestConnection": { "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@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/people/{personId}": { "get": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "getPerson", "summary": "Get a person", "description": "Retrieve an existing person in the workspace.", "tags": [ "People" ], "parameters": [ { "schema": { "type": "string", "minLength": 40, "maxLength": 40 }, "required": true, "description": "The ID of the person to retrieve.", "name": "personId", "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/Person" }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "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", "gender": "Female", "jobTitle": "Software Engineer", "createdAt": "2021-01-01T00:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "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": [ "john@example.com", "john@techcorp.com" ], "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": "jane@example.com" } ] } }, "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": "john.doe@example.com" } ] } }, "strongestConnection": { "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@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": [] } ], "x-stability-level": "alpha", "operationId": "updatePerson", "summary": "Update a person", "description": "Update an existing person in the workspace.", "tags": [ "People" ], "parameters": [ { "schema": { "type": "string", "minLength": 40, "maxLength": 40 }, "required": true, "description": "The ID of the person to update.", "name": "personId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 500, "description": "The first name of the person.", "example": "John" }, "lastName": { "type": "string", "maxLength": 500, "description": "The last name of the person.", "example": "Doe" }, "fullName": { "type": "string", "maxLength": 1000, "description": "The full name of the person.", "example": "John Doe" }, "description": { "type": "string", "maxLength": 5000, "description": "A short description of the person.", "example": "A brief description of the person." }, "birthday": { "anyOf": [ { "type": "string", "minLength": 10, "maxLength": 10, "format": "date" }, { "type": "string", "enum": [ "" ] }, { "type": "null" }, { "type": "null" } ], "description": "The birthday of the person, in ISO format. Deleted with null or empty string.", "example": "1990-01-01" }, "gender": { "type": [ "string", "null" ], "enum": [ "Male", "Female", "Unknown", "Other" ], "description": "The gender of the person. Authorized values are \"Female\", \"Male\", \"Unknown\", \"Other\" or null to delete it.", "example": "Unknown" }, "jobTitle": { "type": "string", "maxLength": 500, "description": "The job title of the person.", "example": "Software Engineer" }, "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 person to. You must provide group ids.", "example": [ { "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2" } ] }, "companies": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 40, "maxLength": 40 } }, "required": [ "id" ], "additionalProperties": false } ] }, "maxItems": 20, "description": "The companies associated with the person. You can either provide a name or an id. If you provide a name, the company will be created if it does not already exist. The first company in the list will be the person's primary company.", "example": [ { "name": "Tech Corp" }, { "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c" } ] }, "addresses": { "type": "array", "items": { "type": "string", "maxLength": 500, "description": "", "example": "" }, "maxItems": 20, "description": "A list of addresses associated with the person. The first address in the list will be the person'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 person. The first email address in the list will be the person'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 person. The first phone number in the list will be the person'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 person. The first URL in the list will be the person'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 person, grouped by group ids. The format is the following:\n```json\n{\n \"\": {\n \"\": \"\"\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", "Programming languages": [ "Javascript", "Python" ], "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": { "Favorite color": "Blue", "Favorite number": 42, "Assignee": [ { "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6" }, { "email": "jane@example.com" } ] } } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated 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/Person" }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "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", "gender": "Female", "jobTitle": "Software Engineer", "createdAt": "2021-01-01T00:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "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": [ "john@example.com", "john@techcorp.com" ], "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": "jane@example.com" } ] } }, "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": "john.doe@example.com" } ] } }, "strongestConnection": { "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@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" } } }, "delete": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "deletePerson", "summary": "Delete a person", "description": "Delete an existing person in the workspace.", "tags": [ "People" ], "parameters": [ { "schema": { "type": "string", "minLength": 40, "maxLength": 40 }, "required": true, "description": "The ID of the person to delete.", "name": "personId", "in": "path" } ], "responses": { "200": { "description": "The ID of the deleted person.", "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": { "id": { "type": "string" } }, "required": [ "id" ], "example": { "id": "per_183ed5cc-3182-45de-84d1-d520f2604810" } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "per_183ed5cc-3182-45de-84d1-d520f2604810" } } } } }, "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/people/search": { "post": { "security": [ { "bearerApiKeyAuth": [] } ], "x-stability-level": "alpha", "x-excluded": true, "operationId": "internal_searchPeople", "summary": "Search for people", "description": "Search for people in the workspace.", "tags": [ "People" ], "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": 512 }, "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" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "combinator": { "type": "string", "enum": [ "and", "or" ], "default": "and" }, "filter": { "type": "object", "additionalProperties": true, "default": {}, "properties": {} } }, "default": { "combinator": "and", "filter": {} } } } } }, "responses": { "200": { "description": "A paginated list of people in the workspace.", "links": { "getPerson": { "operationId": "getPerson", "parameters": { "personId": "$response.body#/data/id" }, "description": "The id returned by the `POST /v1/people` operation can be used as an input to the `GET /v1/people/:personId` operation to retrieve the person." } }, "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/Person" } }, "pagination": { "type": "object", "properties": { "nextLink": { "type": "string" } } } }, "required": [ "items", "pagination" ], "example": { "items": [ { "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", "gender": "Female", "jobTitle": "Software Engineer", "createdAt": "2021-01-01T00:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "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": [ "john@example.com", "john@techcorp.com" ], "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": "jane@example.com" } ] } }, "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": "john.doe@example.com" } ] } }, "strongestConnection": { "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" } } } ], "pagination": { "nextLink": "https://api.folk.app/v1/people?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D" } } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "items": [ { "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", "gender": "Female", "jobTitle": "Software Engineer", "createdAt": "2021-01-01T00:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "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": [ "john@example.com", "john@techcorp.com" ], "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": "jane@example.com" } ] } }, "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": "john.doe@example.com" } ] } }, "strongestConnection": { "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" } } } ], "pagination": { "nextLink": "https://api.folk.app/v1/people?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/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": 512 }, "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", "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 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 \"\": {\n \"\": \"\"\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": { "$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": "updateCompany", "summary": "Update a company", "description": "Update 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 update.", "name": "companyId", "in": "path" } ], "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", "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 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 \"\": {\n \"\": \"\"\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 updated 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": { "$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" } } }, "delete": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "deleteCompany", "summary": "Delete a company", "description": "Delete 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 delete.", "name": "companyId", "in": "path" } ], "responses": { "200": { "description": "The ID of the deleted 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": { "id": { "type": "string" } }, "required": [ "id" ], "example": { "id": "com_183ed5cc-3182-45de-84d1-d520f2604810" } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "com_183ed5cc-3182-45de-84d1-d520f2604810" } } } } }, "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/search": { "post": { "security": [ { "bearerApiKeyAuth": [] } ], "x-excluded": true, "operationId": "internal_searchCompanies", "summary": "Search for companies", "description": "Search for 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": 512 }, "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" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "combinator": { "type": "string", "enum": [ "and", "or" ], "default": "and" }, "filter": { "type": "object", "additionalProperties": true, "default": {}, "properties": {} } }, "default": { "combinator": "and", "filter": {} } } } } }, "responses": { "200": { "description": "A paginated list of companies in the workspace.", "links": { "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." } }, "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" } } } }, "/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": 512 }, "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 \"\": \"\"\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 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", "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 \"\": \"\"\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", "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" } } }, "delete": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "deleteDeal", "summary": "Delete a deal", "description": "Delete 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 delete.", "name": "objectId", "in": "path" } ], "responses": { "200": { "description": "The ID of the deleted 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": { "id": { "type": "string" } }, "required": [ "id" ], "example": { "id": "obj_183ed5cc-3182-45de-84d1-d520f2604810" } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "obj_183ed5cc-3182-45de-84d1-d520f2604810" } } } } }, "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}/search": { "post": { "security": [ { "bearerApiKeyAuth": [] } ], "x-excluded": true, "operationId": "internal_searchDeals", "summary": "Search deals", "description": "Search 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": 512 }, "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" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "combinator": { "type": "string", "enum": [ "and", "or" ], "default": "and" }, "filter": { "type": "object", "additionalProperties": true, "default": {}, "properties": {} } }, "default": { "combinator": "and", "filter": {} } } } } }, "responses": { "200": { "description": "A paginated list of deals in the workspace.", "links": { "getDeal": { "operationId": "getDeal", "parameters": { "dealId": "$response.body#/data/id", "groupId": "$request.path.groupId", "entityType": "$request.path.entityType" }, "description": "Ids returned by the `POST /v1/groups/:groupId/:objectType/search` operation can be used as an input to the `GET /v1/groups/:groupId/:objectType/:dealId` operation to retrieve 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": { "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" } } } }, "/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": 512 }, "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": 512 }, "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" } } } }, "/v1/users": { "get": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "listUsers", "summary": "List users", "description": "Returns a list of workspace users.", "tags": [ "Users" ], "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": 512 }, "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 users in the workspace. The `data.items` field contains the list of users, 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/User" } }, "pagination": { "type": "object", "properties": { "nextLink": { "type": "string" } } } }, "required": [ "items", "pagination" ], "example": { "items": [ { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" } ], "pagination": { "nextLink": "https://api.folk.app/v1/users?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D" } } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "items": [ { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" } ], "pagination": { "nextLink": "https://api.folk.app/v1/users?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/users/me": { "get": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "getCurrentUser", "summary": "Get the current user", "description": "Returns the current workspace user.", "tags": [ "Users" ], "responses": { "200": { "description": "The current user associated with the API key.", "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/CurrentUser" }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@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/users/{userId}": { "get": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "getUser", "summary": "Get a user", "description": "Returns a workspace user.", "tags": [ "Users" ], "parameters": [ { "schema": { "type": "string", "minLength": 40, "maxLength": 40 }, "required": true, "description": "The ID of the user to retrieve.", "example": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "name": "userId", "in": "path" } ], "responses": { "200": { "description": "The retrieved user 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/User" }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@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/notes": { "get": { "security": [ { "bearerApiKeyAuth": [] } ], "x-stability-level": "alpha", "operationId": "listNotes", "summary": "List notes", "description": "Retrieve a list of notes in the workspace.", "tags": [ "Notes" ], "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": 512 }, "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", "minLength": 40, "maxLength": 40 }, "required": false, "description": "Filter notes by entity. Only notes linked to the specified entity will be returned.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b", "name": "entity.id", "in": "query" }, { "schema": { "type": "string", "maxLength": 500 }, "required": false, "description": "Full-text search query against note content.", "example": "onboarding", "name": "query", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "format": "date-time" }, "required": false, "description": "Return only notes created after this ISO 8601 timestamp.", "example": "2024-01-01T00:00:00.000Z", "name": "createdAfter", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "format": "date-time" }, "required": false, "description": "Return only notes created before this ISO 8601 timestamp.", "example": "2024-12-31T23:59:59.999Z", "name": "createdBefore", "in": "query" } ], "responses": { "200": { "description": "A paginated list of notes in the workspace.", "links": { "updateNote": { "operationId": "updateNote", "parameters": { "companyId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/notes` operation can be used as an input to the `PATCH /v1/notes/:noteId` operation to update a note." }, "getNote": { "operationId": "getNote", "parameters": { "companyId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/notes` operation can be used as an input to the `GET /v1/notes/:noteId` operation to retrieve a note." }, "deleteNote": { "operationId": "deleteNote", "parameters": { "companyId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/notes` operation can be used as an input to the `DELETE /v1/notes/:noteId` operation to delete a note." } }, "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/Note" } }, "pagination": { "type": "object", "properties": { "nextLink": { "type": "string" } } } }, "required": [ "items", "pagination" ], "example": { "items": [ { "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "visibility": "public", "content": "This is a note about John Doe", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "parentNote": { "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "content": "This is a parent note about John Doe", "visibility": "public", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "deleted": false } } ], "pagination": { "nextLink": "https://api.folk.app/v1/notes?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D" } } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "items": [ { "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "visibility": "public", "content": "This is a note about John Doe", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "parentNote": { "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "content": "This is a parent note about John Doe", "visibility": "public", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "deleted": false } } ], "pagination": { "nextLink": "https://api.folk.app/v1/notes?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": [] } ], "x-stability-level": "alpha", "operationId": "createNote", "summary": "Create a note", "description": "Create a new note in the workspace.", "tags": [ "Notes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "object", "properties": { "id": { "type": "string", "minLength": 40, "maxLength": 40 } }, "required": [ "id" ], "additionalProperties": false, "description": "The entity connected to the note. You can link people, companies and deals.", "example": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b" } }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the note.\n\n- `public`: The note is visible to all users in the workspace.\n- `private`: The note is visible only to the current user.\n " }, "content": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "The content of the note. Can be in plain text or in markdown format.", "example": "This is a note about **John Doe**" }, "parentNote": { "type": "object", "properties": { "id": { "type": "string", "minLength": 40, "maxLength": 40 } }, "required": [ "id" ], "additionalProperties": false, "description": "The parent note, if this note is a reply to another note.", "example": { "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c" } } }, "required": [ "entity", "visibility", "content" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The note created in the workspace.", "links": { "updateNote": { "operationId": "updateNote", "parameters": { "noteId": "$response.body#/data/id" }, "description": "The id returned by the `POST /v1/notes` operation can be used as an input to the `PATCH /v1/notes/:noteId` operation to update the note." }, "getNote": { "operationId": "getNote", "parameters": { "companyId": "$response.body#/data/id" }, "description": "The id returned by the `POST /v1/notes` operation can be used as an input to the `GET /v1/notes/:noteId` operation to retrieve the note." }, "deleteNote": { "operationId": "deleteNote", "parameters": { "noteId": "$response.body#/data/id" }, "description": "The id returned by the `POST /v1/notes` operation can be used as an input to the `DELETE /v1/notes/:noteId` operation to delete the note." } }, "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/Note" }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "visibility": "public", "content": "This is a note about John Doe", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "parentNote": { "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "content": "This is a parent note about John Doe", "visibility": "public", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "deleted": false } } } } } }, "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/notes/{noteId}": { "get": { "security": [ { "bearerApiKeyAuth": [] } ], "x-stability-level": "alpha", "operationId": "getNote", "summary": "Get a note", "description": "Retrieve an existing note in the workspace.", "tags": [ "Notes" ], "parameters": [ { "schema": { "type": "string", "minLength": 40, "maxLength": 40 }, "required": true, "description": "The ID of the note to retrieve.", "name": "noteId", "in": "path" } ], "responses": { "200": { "description": "The retrieved note 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/Note" }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "visibility": "public", "content": "This is a note about John Doe", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "parentNote": { "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "content": "This is a parent note about John Doe", "visibility": "public", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "deleted": false } } } } } }, "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": [] } ], "x-stability-level": "alpha", "operationId": "updateNote", "summary": "Update a note", "description": "Update an existing note in the workspace.", "tags": [ "Notes" ], "parameters": [ { "schema": { "type": "string", "minLength": 40, "maxLength": 40 }, "required": true, "description": "The ID of the note to update.", "name": "noteId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "The content of the note. Can be in plain text or in markdown format.", "example": "This is a note about **John Doe**" }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the note.\n\n- `public`: The note is visible to all users in the workspace.\n- `private`: The note is visible only to the current user.\n " } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated note 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/Note" }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "visibility": "public", "content": "This is a note about John Doe", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "parentNote": { "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "content": "This is a parent note about John Doe", "visibility": "public", "author": { "type": "user", "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "fullName": "John Doe", "email": "john.doe@example.com", "deleted": false }, "createdAt": "2021-01-01T00:00:00.000Z", "deleted": false } } } } } }, "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" } } }, "delete": { "security": [ { "bearerApiKeyAuth": [] } ], "operationId": "deleteNote", "summary": "Delete a note", "description": "Delete an existing note in the workspace.", "tags": [ "Notes" ], "parameters": [ { "schema": { "type": "string", "minLength": 40, "maxLength": 40 }, "required": true, "description": "The ID of the note to delete.", "name": "noteId", "in": "path" } ], "responses": { "200": { "description": "The ID of the deleted note.", "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": { "id": { "type": "string" } }, "required": [ "id" ], "example": { "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc" } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc" } } } } }, "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/reminders": { "get": { "security": [ { "bearerApiKeyAuth": [] } ], "x-stability-level": "alpha", "operationId": "listReminders", "summary": "List reminders", "description": "Retrieve a list of reminders in the workspace.", "tags": [ "Reminders" ], "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": 512 }, "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", "minLength": 40, "maxLength": 40 }, "required": false, "description": "Filter reminders by entity. Only reminders linked to the specified entity will be returned.", "example": "per_55175e81-9a52-4ac3-930e-82792c23499b", "name": "entity.id", "in": "query" } ], "responses": { "200": { "description": "A paginated list of reminders in the workspace.", "links": { "updateReminder": { "operationId": "updateReminder", "parameters": { "companyId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/reminders` operation can be used as an input to the `PATCH /v1/reminders/:reminderId` operation to update a reminder." }, "getReminder": { "operationId": "getReminder", "parameters": { "companyId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/reminders` operation can be used as an input to the `GET /v1/reminders/:reminderId` operation to retrieve a reminder." }, "deleteReminder": { "operationId": "deleteReminder", "parameters": { "companyId": "$response.body#/data/items/0/id" }, "description": "The ids returned by the `GET /v1/reminders` operation can be used as an input to the `DELETE /v1/reminders/:reminderId` operation to delete a reminder." } }, "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/Reminder" } }, "pagination": { "type": "object", "properties": { "nextLink": { "type": "string" } } } }, "required": [ "items", "pagination" ], "example": { "items": [ { "id": "rmd_91118b73-5a75-480b-b8e3-a33671c35cdc", "name": "Reminder on John Doe", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1", "visibility": "public", "assignedUsers": [ { "id": "usr_a45c30d8-19fc-4939-94c7-17dc5e46f476", "fullName": "John Doe", "email": "john.doe@example.com" } ], "nextTriggerTime": "2025-07-17T09:00:00.000Z", "lastTriggerTime": "2025-05-17T09:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "createdAt": "2021-01-01T00:00:00.000Z" } ], "pagination": { "nextLink": "https://api.folk.app/v1/reminders?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D" } } }, "deprecations": { "type": "array", "items": { "type": "string" }, "example": [ "This field is deprecated" ] } }, "required": [ "data" ] }, "example": { "data": { "items": [ { "id": "rmd_91118b73-5a75-480b-b8e3-a33671c35cdc", "name": "Reminder on John Doe", "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" }, "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1", "visibility": "public", "assignedUsers": [ { "id": "usr_a45c30d8-19fc-4939-94c7-17dc5e46f476", "fullName": "John Doe", "email": "john.doe@example.com" } ], "nextTriggerTime": "2025-07-17T09:00:00.000Z", "lastTriggerTime": "2025-05-17T09:00:00.000Z", "createdBy": { "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71", "fullName": "John Doe", "email": "john.doe@example.com" }, "createdAt": "2021-01-01T00:00:00.000Z" } ], "pagination": { "nextLink": "https://api.folk.app/v1/reminders?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": [] } ], "x-stability-level": "alpha", "operationId": "createReminder", "summary": "Create a reminder", "description": "Create a new reminder in the workspace.", "tags": [ "Reminders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "object", "properties": { "id": { "type": "string", "minLength": 40, "maxLength": 40 } }, "required": [ "id" ], "additionalProperties": false, "description": "The entity connected to the reminder. You can link people, companies and deals.", "example": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b" } }, "name": { "type": "string", "maxLength": 255, "description": "The name of the reminder.", "example": "Reminder on John Doe" }, "recurrenceRule": { "type": "string", "maxLength": 150, "description": "The recurrence rule of the reminder. The recurrence rule is a string that follows the iCalendar format specified in [RFC 5545](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html).\nWe support only a subset of the iCalendar format:\n\n```\nDTSTART;TZID=:T