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.0.3 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: 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 format: date-time description: The last interaction date between the current user and the contact. example: '2025-05-01T00:00:00Z' nullable: true required: - approximateCount - lastInteractedAt workspace: type: object properties: approximateCount: type: integer minimum: 0 description: The approximate number of interactions of your workspace with the contact. example: 42 lastInteractedAt: type: string format: date-time description: The last interaction date of your workspace with the contact. example: '2025-05-01T00:00:00Z' nullable: true lastInteractedBy: type: array items: $ref: '#/components/schemas/User' description: List of users in your workspace who last interacted with the contact. example: - id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: 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 minLength: 10 maxLength: 10 format: date description: The birthday of the person, in ISO format. example: '1990-01-01' nullable: true jobTitle: type: string description: The job title of the person. example: Software Engineer createdAt: type: string minLength: 20 maxLength: 40 description: The date and time the person was created, in ISO format. example: '2021-01-01T00:00:00.000Z' nullable: true createdBy: $ref: '#/components/schemas/User' groups: type: array items: type: object properties: id: type: string name: type: string required: - id - name description: The groups associated with the person. example: - id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 name: Engineering companies: type: array items: type: object properties: id: type: string description: The id of the company. example: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c name: type: string description: The name of the company. example: Tech Corp required: - id - name description: The companies associated with the person. The first company in the list is the person's primary company. example: - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c name: Tech Corp addresses: type: array items: type: string description: An address associated with the person. The first address in the list is the person's primary address. example: 123 Main St, Springfield, USA emails: type: array items: type: string description: An email address associated with the person. The first email address in the list is the person's primary email address. example: 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 - jobTitle - createdAt - createdBy - groups - companies - addresses - emails - phones - urls - customFieldValues - interactionMetadata description: A person in the workspace. example: id: per_183ed5cc-3182-45de-84d1-d520f2604810 firstName: John lastName: Doe fullName: John Doe description: John Doe is a software engineer at Tech Corp. birthday: '1980-06-15' jobTitle: Software Engineer createdAt: '2021-01-01T00:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: 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 description: The amount in USD of funding raised by the company. example: '5000000' nullable: true lastFundingDate: type: string minLength: 10 maxLength: 10 format: date description: The date of the last funding round for the company, in YYYY-MM-DD format. example: '1990-01-01' nullable: true industry: type: string description: The industry the company operates in. example: Technology nullable: true foundationYear: type: string description: The foundation year of the company, in YYYY format. example: '1990' nullable: true employeeRange: type: string description: 'The employee range of the company. Possible values are: "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10000+".' example: 51-200 nullable: true groups: type: array items: type: object properties: id: type: string name: type: string required: - id - name description: The groups associated with the company. example: - id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 name: Engineering addresses: type: array items: type: string description: An address associated with the company. The first address in the list is the company's primary address. example: 123 Main St, Springfield, USA emails: type: array items: type: string description: An email address associated with the company. The first email address in the list is the company's primary email address. example: 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 minLength: 20 maxLength: 40 description: The date and time the company was created, in ISO format. example: '2021-01-01T00:00:00.000Z' nullable: true createdBy: $ref: '#/components/schemas/User' customFieldValues: type: object additionalProperties: type: object additionalProperties: anyOf: - type: 'null' - type: string description: A custom field value as a string. example: Value 1 - type: array items: type: string description: An array of values for the custom field. example: - Value 1 - Value 2 - type: array items: $ref: '#/components/schemas/User' description: An array of users associated with the custom field. example: - id: usr_44b85098-441b-4d7f-9d72-c079b1caec45 fullName: Jane Doe email: 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 minLength: 20 maxLength: 40 description: The date and time the deal was created, in ISO format. example: '2021-01-01T00:00:00.000Z' nullable: true createdBy: $ref: '#/components/schemas/User' customFieldValues: type: object additionalProperties: anyOf: - type: 'null' - type: string description: A custom field value as a string. example: Value 1 - type: array items: type: string description: An array of values for the custom field. example: - Value 1 - Value 2 - type: array items: $ref: '#/components/schemas/User' description: An array of users associated with the custom field. example: - id: usr_44b85098-441b-4d7f-9d72-c079b1caec45 fullName: Jane Doe email: 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 minLength: 20 maxLength: 40 description: The date and time the note was created, in ISO format. example: '2021-01-01T00:00:00.000Z' nullable: true 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 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 nullable: true 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 minLength: 20 maxLength: 40 description: The date and time the parent note was created, in ISO format. example: '2021-01-01T00:00:00.000Z' nullable: true 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 RRULE: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 format: date-time description: The next trigger time of the reminder. example: '2025-07-17T09:00:00.000Z' nullable: true lastTriggerTime: type: string format: date-time description: The last trigger time of the reminder. example: '2025-05-17T09:00:00.000Z' nullable: true createdBy: allOf: - $ref: '#/components/schemas/User' - description: The user who created the reminder. createdAt: type: string minLength: 20 maxLength: 40 description: The date and time the reminder was created, in ISO format. example: '2021-01-01T00:00:00.000Z' nullable: true 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 RRULE: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' LoggedInteraction: type: object properties: id: type: string entity: type: object properties: id: type: string description: The ID of the entity connected to the interaction. example: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: type: string enum: - person - company description: The type of the entity connected to the interaction. Can be `person` or `company`. example: person fullName: type: string description: The full name of the entity connected to the interaction. example: John Doe required: - id - entityType - fullName 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 Discussed the new project.' 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 description: The type of the interaction. Can be a predefined type or an emoji. example: coffee required: - id - entity - dateTime - title - content - type description: An interaction linked to an entity. example: id: lit_b049db09-c03d-4f32-96d6-d314760add5d title: Coffee with John Doe content: 'Had a coffee with John Doe Discussed the new project.' entity: id: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: person fullName: John Doe dateTime: '2025-07-17T09:00:00.000Z' type: 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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query - schema: type: string enum: - and - or default: and required: false description: The logical operator to combine multiple filters. example: and name: combinator in: query - schema: type: object additionalProperties: true default: {} properties: {} required: false description: A record of filters to apply, following the format `filter[attribute][operator]=value`. The `attribute` is the name of the attribute to filter on, and the `operator` is one of the supported filter operators. Refer to [Filterable fields](/api-reference/filtering#filterable-fields) to learn more about the supported attributes and operators. style: deepObject explode: true allowReserved: true examples: fullName_eq: summary: Full name equals "Alice Johnson" value: fullName: eq: Alice Johnson fullName_not_eq: summary: Full name does not equal "Alice Johnson" value: fullName: not_eq: Alice Johnson fullName_like: summary: Full name contains "Alice" value: fullName: like: Alice fullName_not_like: summary: Full name does not contain "Alice" value: fullName: not_like: Alice fullName_empty: summary: Full name is empty value: fullName: empty: '' fullName_not_empty: summary: Full name is not empty value: fullName: not_empty: '' firstName_eq: summary: First name equals "Alice" value: firstName: eq: Alice lastName_eq: summary: Last name equals "Alice" value: lastName: eq: Alice jobTitle_eq: summary: Job title equals "Software Engineer" value: jobTitle: eq: Software Engineer birthday_gt: summary: Birthday is after "1990-01-01" value: birthday: gt: '1990-01-01' description_like: summary: Description contains "developer" value: description: like: developer emails_eq: summary: Emails equals "alice@example.com" value: emails: eq: alice@example.com phones_eq: summary: Phones equals "123-456-7890" value: phones: eq: 123-456-7890 urls_eq: summary: URLs equals "https://example.com" value: urls: eq: https://example.com addresses_eq: summary: Addresses equals "123 Main St" value: addresses: eq: 123 Main St companies_in: summary: Companies includes multiple IDs value: companies: in: id: - com_8a5c68a0-6566-4e30-bdd0-382d708277de - com_d3d63a35-733e-450e-a521-97ed25f5f087 companies_not_in: summary: Companies does not include "com_8a5c68a0-6566-4e30-bdd0-382d708277de" value: companies: not_in: id: com_8a5c68a0-6566-4e30-bdd0-382d708277de companies_empty: summary: Companies is empty value: companies: empty: '' companies_not_empty: summary: Companies is not empty value: companies: not_empty: '' groups_in: summary: Groups includes multiple IDs value: groups: in: id: - grp_721e5288-324a-4f2e-85bd-4a3469987f97 - grp_bee00bb3-48b4-4033-bc9c-a9d173a94c0e textField_eq: summary: Text field equals "Some text value" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Text: eq: Some text value numericField_gt: summary: Number field is greater than "42" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Number: gt: '42' dateField_gt: summary: Date field is after "2023-01-01" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Date: gt: '2023-01-01' singleSelect_in: summary: Single select field includes "Todo" or "In Progress" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Single select: in: - Todo - In Progress multipleSelect_in: summary: Multiple select field includes "B2B" or "B2C" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Multiple select: in: - B2B - B2C userField_in: summary: User field includes a user with the email "john@folk.app" or a user with the id "usr_52401927-bf77-4130-a4cb-aceb295eb5b9" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Assign: in: email: john@folk.app id: usr_52401927-bf77-4130-a4cb-aceb295eb5b9 contactField_in: summary: Contact field includes specific IDs value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Relationship: in: id: - per_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf - com_4b452b53-22c3-4373-94b8-33ef6eb2788f name: filter in: query responses: '200': description: A paginated list of 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' 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' 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: type: string minLength: 10 maxLength: 10 format: date description: The birthday of the person, in ISO format. example: '1990-01-01' nullable: true jobTitle: type: string 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' 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' 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: type: string minLength: 10 maxLength: 10 format: date description: The birthday of the person, in ISO format. example: '1990-01-01' nullable: true jobTitle: type: string 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' 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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query 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' 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' 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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query - schema: type: string enum: - and - or default: and required: false description: The logical operator to combine multiple filters. example: and name: combinator in: query - schema: type: object additionalProperties: true default: {} properties: {} required: false description: A record of filters to apply, following the format `filter[attribute][operator]=value`. The `attribute` is the name of the attribute to filter on, and the `operator` is one of the supported filter operators. Refer to [Filterable fields](/api-reference/filtering#filterable-fields) to learn more about the supported attributes and operators. style: deepObject explode: true allowReserved: true examples: fullName_eq: summary: Full name equals "Alice Johnson" value: fullName: eq: Alice Johnson fullName_not_eq: summary: Full name does not equal "Alice Johnson" value: fullName: not_eq: Alice Johnson fullName_like: summary: Full name contains "Alice" value: fullName: like: Alice fullName_not_like: summary: Full name does not contain "Alice" value: fullName: not_like: Alice fullName_empty: summary: Full name is empty value: fullName: empty: '' fullName_not_empty: summary: Full name is not empty value: fullName: not_empty: '' firstName_eq: summary: First name equals "Alice" value: firstName: eq: Alice lastName_eq: summary: Last name equals "Alice" value: lastName: eq: Alice jobTitle_eq: summary: Job title equals "Software Engineer" value: jobTitle: eq: Software Engineer birthday_gt: summary: Birthday is after "1990-01-01" value: birthday: gt: '1990-01-01' description_like: summary: Description contains "developer" value: description: like: developer emails_eq: summary: Emails equals "alice@example.com" value: emails: eq: alice@example.com phones_eq: summary: Phones equals "123-456-7890" value: phones: eq: 123-456-7890 urls_eq: summary: URLs equals "https://example.com" value: urls: eq: https://example.com addresses_eq: summary: Addresses equals "123 Main St" value: addresses: eq: 123 Main St companies_in: summary: Companies includes multiple IDs value: companies: in: id: - com_8a5c68a0-6566-4e30-bdd0-382d708277de - com_d3d63a35-733e-450e-a521-97ed25f5f087 companies_not_in: summary: Companies does not include "com_8a5c68a0-6566-4e30-bdd0-382d708277de" value: companies: not_in: id: com_8a5c68a0-6566-4e30-bdd0-382d708277de companies_empty: summary: Companies is empty value: companies: empty: '' companies_not_empty: summary: Companies is not empty value: companies: not_empty: '' groups_in: summary: Groups includes multiple IDs value: groups: in: id: - grp_721e5288-324a-4f2e-85bd-4a3469987f97 - grp_bee00bb3-48b4-4033-bc9c-a9d173a94c0e textField_eq: summary: Text field equals "Some text value" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Text: eq: Some text value numericField_gt: summary: Number field is greater than "42" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Number: gt: '42' dateField_gt: summary: Date field is after "2023-01-01" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Date: gt: '2023-01-01' singleSelect_in: summary: Single select field includes "Todo" or "In Progress" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Single select: in: - Todo - In Progress multipleSelect_in: summary: Multiple select field includes "B2B" or "B2C" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Multiple select: in: - B2B - B2C userField_in: summary: User field includes a user with the email "john@folk.app" or a user with the id "usr_52401927-bf77-4130-a4cb-aceb295eb5b9" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Assign: in: email: john@folk.app id: usr_52401927-bf77-4130-a4cb-aceb295eb5b9 contactField_in: summary: Contact field includes specific IDs value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Relationship: in: id: - per_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf - com_4b452b53-22c3-4373-94b8-33ef6eb2788f name: filter in: query responses: '200': description: A paginated list of companies in the workspace. links: updateCompany: operationId: updateCompany parameters: companyId: $response.body#/data/items/0/id description: The ids returned by the `GET /v1/companies` operation can be used as an input to the `PATCH /v1/companies/:companyId` operation to update a company. getCompany: operationId: getCompany parameters: companyId: $response.body#/data/items/0/id description: The ids returned by the `GET /v1/companies` operation can be used as an input to the `GET /v1/companies/:companyId` operation to retrieve a company. deleteCompany: operationId: deleteCompany parameters: companyId: $response.body#/data/items/0/id description: The ids returned by the `GET /v1/companies` operation can be used as an input to the `DELETE /v1/companies/:companyId` operation to delete a company. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/Company' pagination: type: object properties: nextLink: type: string required: - items - pagination example: items: - id: com_183ed5cc-3182-45de-84d1-d520f2604810 name: Tech Corp description: A leading technology company. fundingRaised: '5000000' lastFundingDate: '1990-01-01' industry: Technology foundationYear: '1990' employeeRange: 51-200 groups: - id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 name: Engineering addresses: - 123 Main St, Springfield, USA - 456 Main St, Springfield, USA emails: - john@example.com - john@techcorp.com phones: - '+1234567890' - +0987654321 urls: - https://example.com createdAt: '2021-01-01T00:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com customFieldValues: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2: Status: Active Business type: - B2B - B2C Join date: '2021-01-01' Relationships: - id: per_ed110a47-5d09-43bf-b2e2-791d8231eb5f fullName: Bob Smith entityType: person - id: com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03 fullName: HR services entityType: company grp_acdf2ad9-6a66-4d32-8594-9694913ac717: Custom Notes: Important client, handle with care. ARR: '42000000' Assignee: - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6 fullName: Jane Doe email: jane@example.com pagination: nextLink: https://api.folk.app/v1/companies?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D deprecations: type: array items: type: string example: - This field is deprecated required: - data example: data: items: - id: com_183ed5cc-3182-45de-84d1-d520f2604810 name: Tech Corp description: A leading technology company. fundingRaised: '5000000' lastFundingDate: '1990-01-01' industry: Technology foundationYear: '1990' employeeRange: 51-200 groups: - id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 name: Engineering addresses: - 123 Main St, Springfield, USA - 456 Main St, Springfield, USA emails: - john@example.com - john@techcorp.com phones: - '+1234567890' - +0987654321 urls: - https://example.com createdAt: '2021-01-01T00:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com customFieldValues: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2: Status: Active Business type: - B2B - B2C Join date: '2021-01-01' Relationships: - id: per_ed110a47-5d09-43bf-b2e2-791d8231eb5f fullName: Bob Smith entityType: person - id: com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03 fullName: HR services entityType: company grp_acdf2ad9-6a66-4d32-8594-9694913ac717: Custom Notes: Important client, handle with care. ARR: '42000000' Assignee: - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6 fullName: Jane Doe email: jane@example.com pagination: nextLink: https://api.folk.app/v1/companies?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' post: security: - bearerApiKeyAuth: [] operationId: createCompany summary: Create a company description: Create a new company in the workspace. tags: - Companies requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 1000 description: The name of the company. example: Tech Corp description: type: string maxLength: 5000 description: A short description of the company. example: A brief description of the company. fundingRaised: anyOf: - type: number description: The amount of funding raised by the company in USD, as a number. example: 100000 - type: string minLength: 1 maxLength: 20 description: The amount of funding raised by the company in USD, as a string. example: '100000' - type: 'null' - type: 'null' lastFundingDate: type: string minLength: 10 maxLength: 10 format: date description: The date of the last funding round for the company, in YYYY-MM-DD format. example: '1990-01-01' nullable: true industry: type: string maxLength: 1000 description: The industry the company operates in. example: Technology nullable: true foundationYear: anyOf: - type: string minLength: 4 maxLength: 4 pattern: ^\d{4}$ description: The foundation year of the company, in YYYY format as string. example: '1990' - type: number minimum: 1000 maximum: 2100 description: The foundation year of the company, in YYYY format as number. example: 1990 - type: 'null' - type: 'null' employeeRange: type: string enum: - 1-10 - 11-50 - 51-200 - 201-500 - 501-1000 - 1001-5000 - 5001-10000 - 10000+ description: The employee range of the company. example: 51-200 nullable: true groups: type: array items: type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id additionalProperties: false maxItems: 100 description: The groups to add the company to. You must provide group ids. example: - id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 addresses: type: array items: type: string maxLength: 500 description: '' example: '' maxItems: 20 description: A list of addresses associated with the company. The first address in the list will be the company's primary address. example: - 123 Main St, Springfield, USA - 456 Main St, Springfield, USA emails: type: array items: type: string maxLength: 254 description: '' example: '' maxItems: 20 description: A list of email addresses associated with the company. The first email address in the list will be the company's primary email address. example: - john@example.com - john@techcorp.com phones: type: array items: type: string maxLength: 30 description: '' example: '' maxItems: 20 description: A list of phone numbers associated with the company. The first phone number in the list will be the company's primary phone number. example: - '+1234567890' - +0987654321 urls: type: array items: type: string maxLength: 2048 description: '' example: '' maxItems: 20 description: A list of URLs associated with the company. The first URL in the list will be the company's primary URL. example: - https://example.com - https://example.com/about customFieldValues: type: object additionalProperties: type: object additionalProperties: anyOf: - type: 'null' - type: string maxLength: 5000 - type: number minimum: -1.7976931348623157e+308 maximum: 1.7976931348623157e+308 - type: array items: anyOf: - type: string maxLength: 500 - type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id - type: object properties: email: type: string maxLength: 254 required: - email maxItems: 1000 - type: 'null' properties: {} description: "The custom field values associated with the company,\ \ grouped by group ids. The format is the following:\n```json\n\ {\n \"\": {\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 minLength: 10 maxLength: 10 format: date description: The date of the last funding round for the company, in YYYY-MM-DD format. example: '1990-01-01' nullable: true industry: type: string maxLength: 1000 description: The industry the company operates in. example: Technology nullable: true foundationYear: anyOf: - type: string minLength: 4 maxLength: 4 pattern: ^\d{4}$ description: The foundation year of the company, in YYYY format as string. example: '1990' - type: number minimum: 1000 maximum: 2100 description: The foundation year of the company, in YYYY format as number. example: 1990 - type: 'null' - type: 'null' employeeRange: type: string enum: - 1-10 - 11-50 - 51-200 - 201-500 - 501-1000 - 1001-5000 - 5001-10000 - 10000+ description: The employee range of the company. example: 51-200 nullable: true groups: type: array items: type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id additionalProperties: false maxItems: 100 description: The groups to add the company to. You must provide group ids. example: - id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 addresses: type: array items: type: string maxLength: 500 description: '' example: '' maxItems: 20 description: A list of addresses associated with the company. The first address in the list will be the company's primary address. example: - 123 Main St, Springfield, USA - 456 Main St, Springfield, USA emails: type: array items: type: string maxLength: 254 description: '' example: '' maxItems: 20 description: A list of email addresses associated with the company. The first email address in the list will be the company's primary email address. example: - john@example.com - john@techcorp.com phones: type: array items: type: string maxLength: 30 description: '' example: '' maxItems: 20 description: A list of phone numbers associated with the company. The first phone number in the list will be the company's primary phone number. example: - '+1234567890' - +0987654321 urls: type: array items: type: string maxLength: 2048 description: '' example: '' maxItems: 20 description: A list of URLs associated with the company. The first URL in the list will be the company's primary URL. example: - https://example.com - https://example.com/about customFieldValues: type: object additionalProperties: type: object additionalProperties: anyOf: - type: 'null' - type: string maxLength: 5000 - type: number minimum: -1.7976931348623157e+308 maximum: 1.7976931348623157e+308 - type: array items: anyOf: - type: string maxLength: 500 - type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id - type: object properties: email: type: string maxLength: 254 required: - email maxItems: 1000 - type: 'null' properties: {} description: "The custom field values associated with the company,\ \ grouped by group ids. The format is the following:\n```json\n\ {\n \"\": {\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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query 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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query - schema: type: string enum: - and - or default: and required: false description: The logical operator to combine multiple filters. example: and name: combinator in: query - schema: type: object additionalProperties: true default: {} properties: {} required: false description: A record of filters to apply, following the format `filter[attribute][operator]=value`. The `attribute` is the name of the attribute to filter on, and the `operator` is one of the supported filter operators. Refer to [Filterable fields](/api-reference/filtering#filterable-fields) to learn more about the supported attributes and operators. style: deepObject explode: true allowReserved: true examples: fullName_eq: summary: Full name equals "Alice Johnson" value: fullName: eq: Alice Johnson fullName_not_eq: summary: Full name does not equal "Alice Johnson" value: fullName: not_eq: Alice Johnson fullName_like: summary: Full name contains "Alice" value: fullName: like: Alice fullName_not_like: summary: Full name does not contain "Alice" value: fullName: not_like: Alice fullName_empty: summary: Full name is empty value: fullName: empty: '' fullName_not_empty: summary: Full name is not empty value: fullName: not_empty: '' firstName_eq: summary: First name equals "Alice" value: firstName: eq: Alice lastName_eq: summary: Last name equals "Alice" value: lastName: eq: Alice jobTitle_eq: summary: Job title equals "Software Engineer" value: jobTitle: eq: Software Engineer birthday_gt: summary: Birthday is after "1990-01-01" value: birthday: gt: '1990-01-01' description_like: summary: Description contains "developer" value: description: like: developer emails_eq: summary: Emails equals "alice@example.com" value: emails: eq: alice@example.com phones_eq: summary: Phones equals "123-456-7890" value: phones: eq: 123-456-7890 urls_eq: summary: URLs equals "https://example.com" value: urls: eq: https://example.com addresses_eq: summary: Addresses equals "123 Main St" value: addresses: eq: 123 Main St companies_in: summary: Companies includes multiple IDs value: companies: in: id: - com_8a5c68a0-6566-4e30-bdd0-382d708277de - com_d3d63a35-733e-450e-a521-97ed25f5f087 companies_not_in: summary: Companies does not include "com_8a5c68a0-6566-4e30-bdd0-382d708277de" value: companies: not_in: id: com_8a5c68a0-6566-4e30-bdd0-382d708277de companies_empty: summary: Companies is empty value: companies: empty: '' companies_not_empty: summary: Companies is not empty value: companies: not_empty: '' groups_in: summary: Groups includes multiple IDs value: groups: in: id: - grp_721e5288-324a-4f2e-85bd-4a3469987f97 - grp_bee00bb3-48b4-4033-bc9c-a9d173a94c0e textField_eq: summary: Text field equals "Some text value" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Text: eq: Some text value numericField_gt: summary: Number field is greater than "42" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Number: gt: '42' dateField_gt: summary: Date field is after "2023-01-01" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Date: gt: '2023-01-01' singleSelect_in: summary: Single select field includes "Todo" or "In Progress" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Single select: in: - Todo - In Progress multipleSelect_in: summary: Multiple select field includes "B2B" or "B2C" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Multiple select: in: - B2B - B2C userField_in: summary: User field includes a user with the email "john@folk.app" or a user with the id "usr_52401927-bf77-4130-a4cb-aceb295eb5b9" value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Assign: in: email: john@folk.app id: usr_52401927-bf77-4130-a4cb-aceb295eb5b9 contactField_in: summary: Contact field includes specific IDs value: customFieldValues.grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2.Relationship: in: id: - per_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf - com_4b452b53-22c3-4373-94b8-33ef6eb2788f name: filter in: query responses: '200': description: A paginated list of deals in the workspace. links: updateDeal: operationId: updateDeal parameters: dealId: $response.body#/data/items/0/id groupId: $request.path.groupId entityType: $request.path.entityType description: The ids returned by the `GET /v1/groups/:groupId/:objectType` operation can be used as an input to the `PATCH /v1/groups/:groupId/:objectType/:dealId` operation to update a deal. getDeal: operationId: getDeal parameters: dealId: $response.body#/data/items/0/id groupId: $request.path.groupId entityType: $request.path.entityType description: The ids returned by the `GET /v1/groups/:groupId/:objectType` operation can be used as an input to the `GET /v1/groups/:groupId/:objectType/:dealId` operation to retrieve a deal. deleteDeal: operationId: deleteDeal parameters: dealId: $response.body#/data/items/0/id groupId: $request.path.groupId entityType: $request.path.entityType description: The ids returned by the `GET /v1/groups/:groupId/:objectType` operation can be used as an input to the `DELETE /v1/groups/:groupId/:objectType/:dealId` operation to delete a deal. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/Deal' pagination: type: object properties: nextLink: type: string required: - items - pagination example: items: - id: obj_183ed5cc-3182-45de-84d1-d520f2604810 name: Project Alpha companies: - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c name: Tech Corp people: - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 fullName: John Doe createdAt: '2021-01-01T00:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com customFieldValues: Status: Active Deal value: '42000' Close date: '2021-01-01' Assignee: - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6 fullName: Jane Doe email: jane@example.com pagination: nextLink: https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D deprecations: type: array items: type: string example: - This field is deprecated required: - data example: data: items: - id: obj_183ed5cc-3182-45de-84d1-d520f2604810 name: Project Alpha companies: - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c name: Tech Corp people: - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 fullName: John Doe createdAt: '2021-01-01T00:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com customFieldValues: Status: Active Deal value: '42000' Close date: '2021-01-01' Assignee: - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6 fullName: Jane Doe email: jane@example.com pagination: nextLink: https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' post: security: - bearerApiKeyAuth: [] operationId: createDeal summary: Create a deal description: Create a new deal in the workspace. tags: - Deals parameters: - schema: type: string minLength: 40 maxLength: 40 required: true description: The ID of the group the deals belong to. Can be retrieved from the [List groups](/api-reference/groups/list-groups) endpoint. example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71 name: groupId in: path - schema: type: string maxLength: 500 required: true description: The name of a deal custom field that can be retrieved from the [List group custom fields](/api-reference/groups/list-group-custom-fields) endpoint. example: Deals name: objectType in: path requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 1000 description: The name of the deal. example: Project Alpha companies: type: array items: type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id additionalProperties: false maxItems: 20 description: The companies associated with the deal. example: - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c people: type: array items: type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id additionalProperties: false maxItems: 20 description: The people associated with the deal. example: - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 customFieldValues: type: object additionalProperties: anyOf: - type: 'null' - type: string maxLength: 5000 - type: number minimum: -1.7976931348623157e+308 maximum: 1.7976931348623157e+308 - type: array items: anyOf: - type: string maxLength: 500 - type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id - type: object properties: email: type: string maxLength: 254 required: - email maxItems: 1000 - type: 'null' description: "The custom field values associated with the deal.\ \ The format is the following:\n```json\n{\n \"\"\ : \"\"\n}\n```\n\nThe format of the custom field\ \ value depends on the type of the custom field:\n\n- `textField`:\ \ string, eg: `\"Foo\"`\n- `numericField`: number or numeric string,\ \ eg: `42` or `\"42\"`\n- `dateField`: ISO 8601 string (YYYY-MM-DD),\ \ eg: `\"2021-01-01\"`\n- `singleSelect`: string (option label),\ \ eg: `\"Active\"`\n- `multipleSelect`: array of strings (option\ \ labels), eg: `[\"B2B\", \"B2C\"]`\n- `userField`: array of objects\ \ with either `id` (workspace user id) or `email` (workspace user\ \ email) property, eg: `[{\"id\": \"usr_a23373bb-5296-4c59-b2e8-8f121707d562\"\ }, {\"email\": \"jane@example.com\"}]`\n\nPassing a `null` value\ \ or an empty array will unset the custom field value." properties: {} example: Status: Active Deal value: '42000' Close date: '2021-01-01' Assignee: - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6 - email: jane@example.com additionalProperties: false responses: '200': description: The deal created in the workspace. links: updateDeal: operationId: updateDeal parameters: dealId: $response.body#/data/id groupId: $request.path.groupId entityType: $request.path.entityType description: The id returned by the `POST /v1/groups/:groupId/:objectType` operation can be used as an input to the `PATCH /v1/groups/:groupId/:objectType/:dealId` operation to update the deal. getDeal: operationId: getDeal parameters: dealId: $response.body#/data/id groupId: $request.path.groupId entityType: $request.path.entityType description: The id returned by the `POST /v1/groups/:groupId/:objectType` operation can be used as an input to the `GET /v1/groups/:groupId/:objectType/:dealId` operation to retrieve the deal. deleteDeal: operationId: deleteDeal parameters: dealId: $response.body#/data/id groupId: $request.path.groupId entityType: $request.path.entityType description: The id returned by the `POST /v1/groups/:groupId/:objectType` operation can be used as an input to the `DELETE /v1/groups/:groupId/:objectType/:dealId` operation to delete the deal. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Deal' deprecations: type: array items: type: string example: - This field is deprecated required: - data example: data: id: obj_183ed5cc-3182-45de-84d1-d520f2604810 name: Project Alpha companies: - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c name: Tech Corp people: - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 fullName: John Doe createdAt: '2021-01-01T00:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com customFieldValues: Status: Active Deal value: '42000' Close date: '2021-01-01' Assignee: - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6 fullName: Jane Doe email: jane@example.com '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/groups/{groupId}/{objectType}/{objectId}: get: security: - bearerApiKeyAuth: [] operationId: getDeal summary: Get a deal description: Retrieve an existing deal in the workspace. tags: - Deals parameters: - schema: type: string minLength: 40 maxLength: 40 required: true description: The ID of the group the deals belong to. Can be retrieved from the [List groups](/api-reference/groups/list-groups) endpoint. example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71 name: groupId in: path - schema: type: string maxLength: 500 required: true description: The name of a deal custom field that can be retrieved from the [List group custom fields](/api-reference/groups/list-group-custom-fields) endpoint. example: Deals name: objectType in: path - schema: type: string minLength: 40 maxLength: 40 required: true description: The ID of the deal to retrieve. name: objectId in: path responses: '200': description: The retrieved person in the workspace. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Deal' deprecations: type: array items: type: string example: - This field is deprecated required: - data example: data: id: obj_183ed5cc-3182-45de-84d1-d520f2604810 name: Project Alpha companies: - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c name: Tech Corp people: - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 fullName: John Doe createdAt: '2021-01-01T00:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com customFieldValues: Status: Active Deal value: '42000' Close date: '2021-01-01' Assignee: - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6 fullName: Jane Doe email: jane@example.com '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' patch: security: - bearerApiKeyAuth: [] operationId: updateDeal summary: Update a deal description: Update an existing deal in the workspace. tags: - Deals parameters: - schema: type: string minLength: 40 maxLength: 40 required: true description: The ID of the group the deals belong to. Can be retrieved from the [List groups](/api-reference/groups/list-groups) endpoint. example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71 name: groupId in: path - schema: type: string maxLength: 500 required: true description: The name of a deal custom field that can be retrieved from the [List group custom fields](/api-reference/groups/list-group-custom-fields) endpoint. example: Deals name: objectType in: path - schema: type: string minLength: 40 maxLength: 40 required: true description: The ID of the deal to update. name: objectId in: path requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 1000 description: The name of the deal. example: Project Alpha companies: type: array items: type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id additionalProperties: false maxItems: 20 description: The companies associated with the deal. example: - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c people: type: array items: type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id additionalProperties: false maxItems: 20 description: The people associated with the deal. example: - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2 customFieldValues: type: object additionalProperties: anyOf: - type: 'null' - type: string maxLength: 5000 - type: number minimum: -1.7976931348623157e+308 maximum: 1.7976931348623157e+308 - type: array items: anyOf: - type: string maxLength: 500 - type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id - type: object properties: email: type: string maxLength: 254 required: - email maxItems: 1000 - type: 'null' description: "The custom field values associated with the deal.\ \ The format is the following:\n```json\n{\n \"\"\ : \"\"\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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query 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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query responses: '200': description: A paginated list of groups in the workspace. The `data.items` field contains the list of groups, and the `data.pagination.nextLink` field contains a link to the next page of results, if available. links: listGroupCustomFields: operationId: listGroupCustomFields parameters: groupId: $response.body#/data/items/0/id description: The ids returned by the `/v1/groups` operation can be used as an input to the `/v1/groups/:groupId/custom-fields/:entityType` operation, to retrieve the custom fields for a specific group. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/Group' pagination: type: object properties: nextLink: type: string required: - items - pagination example: items: - id: grp_bc984b3f-0386-434d-82d7-a91eb6badd71 name: Group Name pagination: nextLink: https://api.folk.app/v1/groups?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D deprecations: type: array items: type: string example: - This field is deprecated required: - data example: data: items: - id: grp_bc984b3f-0386-434d-82d7-a91eb6badd71 name: Group Name pagination: nextLink: https://api.folk.app/v1/groups?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/groups/{groupId}/custom-fields/{entityType}: get: security: - bearerApiKeyAuth: [] x-stability-level: alpha operationId: listGroupCustomFields summary: List group custom fields description: Returns a list of group custom fields for an entity type. tags: - Groups parameters: - schema: type: string minLength: 40 maxLength: 40 required: true description: The identifier of the group. You can retrieve a list of group identifiers using the `/v1/groups` endpoint. example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71 name: groupId in: path - schema: type: string maxLength: 500 required: true description: The entity type the custom fields belong to. It can be `person`, `company`, or a custom object name. example: person name: entityType in: path - schema: type: integer minimum: 1 maximum: 100 default: 20 required: false description: The number of items to return. example: 20 name: limit in: query - schema: type: string maxLength: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query responses: '200': description: A paginated list of group custom fields for an entity type. The `data.items` field contains the list of group custom fields, and the `data.pagination.nextLink` field contains a link to the next page of results, if available. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/GroupCustomField' pagination: type: object properties: nextLink: type: string required: - items - pagination example: items: - name: Status type: singleSelect options: - label: Active color: '#ffffff' - label: Inactive color: '#000000' - name: Total Revenue type: numericField config: format: currency currency: USD - name: Details type: textField - name: Tags type: multipleSelect options: - label: Tag 1 color: '#ffffff' - label: Tag 2 color: '#000000' - name: Relationships type: contactField - name: Date type: dateField - name: Assigned to type: userField - name: Deals type: objectField pagination: nextLink: https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/custom-fields/person?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D deprecations: type: array items: type: string example: - This field is deprecated required: - data example: data: items: - name: Status type: singleSelect options: - label: Active color: '#ffffff' - label: Inactive color: '#000000' - name: Total Revenue type: numericField config: format: currency currency: USD - name: Details type: textField - name: Tags type: multipleSelect options: - label: Tag 1 color: '#ffffff' - label: Tag 2 color: '#000000' - name: Relationships type: contactField - name: Date type: dateField - name: Assigned to type: userField - name: Deals type: objectField pagination: nextLink: https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/custom-fields/person?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query responses: '200': description: A paginated list of 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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query - schema: type: string 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 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: 128 required: false description: A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `pagination.nextLink` value returned in a previous response to request subsequent results. example: eyJvZmZzZXQiOjN9 name: cursor in: query - schema: type: string 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 RRULE: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 RRULE: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).\n\ We support only a subset of the iCalendar format:\n\n```\nDTSTART;TZID=:T