openapi: 3.0.3
info:
  title: Folk External Companies API
  description: Folk's public REST API lets you manage workspaces, groups, contacts, and real-time triggers.
  version: '2025-06-09'
  contact:
    name: folk
    email: tech@folk.app
    url: https://folk.app
servers:
- url: https://api.folk.app
  description: Folk's public API production base URL.
  x-internal: false
tags:
- name: Companies
  description: Operations related to companies.
paths:
  /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  \"<groupId>\": {\n    \"<customFieldName>\": \"<customFieldValue>\"\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  \"<groupId>\": {\n    \"<customFieldName>\": \"<customFieldValue>\"\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'
components:
  responses:
    Forbidden:
      description: The API key doesn’t have permissions to perform the request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: The API key doesn’t have permissions to perform the request.
              documentationUrl: https://developer.folk.app/api-reference/errors#forbidden
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    ServiceUnavailable:
      description: The server is overloaded or down for maintenance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SERVICE_UNAVAILABLE
              message: The service is currently unavailable.
              documentationUrl: https://developer.folk.app/api-reference/errors#service-unavailable
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    NotFound:
      description: The requested resource doesn’t exist.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              documentationUrl: https://developer.folk.app/api-reference/errors#not-found
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    InternalServerError:
      description: Something went wrong on our end.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An internal server error occurred.
              documentationUrl: https://developer.folk.app/api-reference/errors#internal-server-error
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    UnprocessableEntity:
      description: The request was unacceptable, often due to missing or invalid parameters.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNPROCESSABLE_ENTITY
              message: Invalid query parameters
              documentationUrl: https://developer.folk.app/api-reference/errors#unprocessable-entity
              details:
                issues:
                - code: too_small
                  minimum: 1
                  type: number
                  inclusive: true
                  exact: false
                  message: Number must be greater than or equal to 1
                  path:
                  - limit
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Unauthorized:
      description: No valid API key provided.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: No valid API key provided.
              documentationUrl: https://developer.folk.app/api-reference/errors#unauthorized
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    TooManyRequests:
      description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RATE_LIMIT_EXCEEDED
              message: The rate limit has been exceeded.
              documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
              details:
                limit: 1000
                remaining: 0
                retryAfter: '2025-10-01T12:00:00Z'
    BadRequest:
      description: The request was unacceptable, often due to missing an invalid parameter.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_REQUEST
              message: The request was invalid.
              documentationUrl: https://developer.folk.app/api-reference/errors#bad-request
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
  schemas:
    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
    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.
    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
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 1000
      description: The maximum number of requests that you can make in the current rate limit window.
    Retry-After:
      schema:
        type: integer
        example: 60
      description: The number of seconds to wait before making a new request after hitting the rate limit.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1747322958
      description: The time at which the current rate limit window resets, in UTC epoch seconds.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 998
      description: The number of requests remaining in the current rate limit window.
  securitySchemes:
    bearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key for authentication