openapi: 3.1.1
info:
  title: Leadfeeder Public API
  version: "2026-05-04"
  license:
    name: mit
    url: https://opensource.org/licenses/MIT
  description: This specification is work in progress. The 'summary' field contains information on the implementation status of an endpoint.
  termsOfService: https://www.leadfeeder.com/terms-and-conditions/
servers:
  - url: https://api.leadfeeder.com
security:
  - ApiKeyAuth: []
externalDocs:
  description: Official API documentation
  url: https://docs.leadfeeder.com/api/public
paths:
  /v1/accounts:
    get:
      operationId: getAccountInfo
      tags:
        - Account
        - v1
      summary: List Accounts
      description: Retrieves a list of Leadfeeder accounts associated with this API key. When listing all accounts, only the account names are returned. Detailed credit information is accessible only when querying a specific account.
      parameters:
        - $ref: '#/components/parameters/AccountIdOptional'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - data
                      - meta
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AccountV1'
                      meta:
                        type: object
                        required:
                          - request_id
                        properties:
                          request_id:
                            type: string
                            description: A unique identifier assigned to each API request for end-to-end traceability.
                            example: cf054205-dd8c-4473-8689-07c30fe0789f
                    additionalProperties: false
                    title: Single account with credit details
                  - type: object
                    required:
                      - data
                      - meta
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AccountSummaryV1'
                      meta:
                        type: object
                        required:
                          - request_id
                        properties:
                          request_id:
                            type: string
                            description: A unique identifier assigned to each API request for end-to-end traceability.
                            example: cf054205-dd8c-4473-8689-07c30fe0789f
                    additionalProperties: false
                    title: Multiple accounts without credit details
                description: |
                  If `account_id` is supplied, the response includes one account with credit details; if omitted, the response is an array of accounts without credit information.
              examples:
                singleAccount:
                  summary: Single account with credit details
                  value:
                    data:
                      - type: account
                        id: '123456'
                        attributes:
                          name: Account 1
                          credits:
                            available: 1000
                            used: 200
                            remaining: 800
                            next_reset_on: '2026-10-01'
                    meta:
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
                multipleAccounts:
                  summary: Multiple accounts without credit details
                  value:
                    data:
                      - type: account_summary
                        id: '123456'
                        attributes:
                          name: Account 1
                      - type: account_summary
                        id: '789012'
                        attributes:
                          name: Account 2
                      - type: account_summary
                        id: '345678'
                        attributes:
                          name: Account 3
                    meta:
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies/{id}:
    get:
      operationId: getCompany
      tags:
        - Companies
        - v1
      summary: Get Company Details
      description: |-
        Fetch detailed information about a specific company, including firmographics and hierarchy information based on the provided Leadfeeder company_id.
        Credit Note: Accessing full deep data consumes 1 credit, unless the company was already accessed within the last 12 months.
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/AccountId'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - group_company
              - tags
              - lists
              - web_visits
              - icps
              - crm_connections
              - crm_connections.crm_record
              - crm_connections.crm_record.crm_owner
              - crm_suggestions
              - crm_suggestions.crm_record
              - crm_suggestions.crm_record.crm_owner
              - crm_group_connections
              - crm_group_connections.crm_connection
              - crm_group_connections.crm_connection.crm_record
              - crm_group_connections.crm_connection.crm_record.crm_owner
          description: Specify which additional data should be attached to the result.
          example: group_company
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/CompanyV1'
                  meta:
                    type: object
                    required:
                      - request_id
                      - credits
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies:
    get:
      operationId: getCompanies
      tags:
        - Companies
        - v1
      summary: Retrieve Companies
      description: |-
        Retrieve the list of companies based on provided IDs.
        Credit Note: Each company will contain it's full deep data and it will consumes 1 credit, unless the company was already accessed within the last 12 months.
      parameters:
        - $ref: '#/components/parameters/CompanyIds'
        - $ref: '#/components/parameters/AccountId'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - group_company
              - tags
              - lists
              - web_visits
              - icps
              - crm_connections
              - crm_connections.crm_record
              - crm_connections.crm_record.crm_owner
              - crm_suggestions
              - crm_suggestions.crm_record
              - crm_suggestions.crm_record.crm_owner
              - crm_group_connections
              - crm_group_connections.crm_connection
              - crm_group_connections.crm_connection.crm_record
              - crm_group_connections.crm_connection.crm_record.crm_owner
          description: Specify which additional data should be attached to the result.
          example: group_company
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyV1'
                  meta:
                    type: object
                    required:
                      - request_id
                      - credits
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Invalid mandatory fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              examples:
                missing_mandatory_fields:
                  value:
                    errors:
                      - code: missing_mandatory_fields
                        title: 'Missing required request parameters: [ids]'
                invalid_parameter:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The list of IDs is required and cannot be left empty.
                too_many_ids:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The number of IDs supplied exceeds the permitted limit of 100.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies/{id}/financials:
    get:
      operationId: getCompanyFinancials
      tags:
        - Companies
        - v1
      summary: Company Financial Reports
      description: |-
        Returns all financial reports for a given company.
        Credit Note: Accessing financial data consumes 1 credit per company only if financial data is available and there was no active deep data access within the last 12 months. Once charged, no additional credits are consumed for accessing the same company’s financial data again within that 12-month period.
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyFinancialsV1'
                  meta:
                    type: object
                    required:
                      - request_id
                      - credits
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies/ips:
    get:
      operationId: getCompanyIps
      tags:
        - Companies
        - v1
      summary: Retrieve Company IPs
      description: |-
        Fetch known IP addresses associated with a given set of companies, enabling identification of web traffic and network activity linked to those organizations based on the provided company IDs.
        Credit Note: Retrieving IP address data consumes 1 credit per company, unless the company's IP data was already accessed within the last 12 months.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: company_ids
          in: query
          description: A comma-separated list of Dealfront company IDs. Accepts up to 100 company IDs per request.
          required: true
          schema:
            type: string
          example: 4b7e2c9f,5c8f3d0a
        - name: max_ip_addresses
          in: query
          description: Maximum number of IP addresses to return per company. Results are ordered by confidence score (highest first).
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - company
          description: Specify which additional data should be attached to the result. When `company` is included, the full company attributes are inlined in the `relationships.company` field. Otherwise only `id` and `type` are returned.
          example: company
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyIpV1'
                  meta:
                    type: object
                    required:
                      - request_id
                      - credits
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  - type: company_ip
                    id: 4b7e2c9f
                    attributes:
                      ips:
                        - 192.0.2.1-192.0.2.255
                        - 192.0.3.1-192.0.3.255
                      ips_extended:
                        - start_ip: 192.0.2.1
                          end_ip: 192.0.2.255
                          confidence_score: very_high
                          location:
                            country_code: DE
                            region: Bavaria
                            city: Munich
                            geonames_id: '2867714'
                        - start_ip: 192.0.3.1
                          end_ip: 192.0.3.255
                          confidence_score: high
                          location:
                            country_code: DE
                            region: Bavaria
                            city: Munich
                            geonames_id: '2867714'
                      has_other_group_companies_with_ips: false
                    relationships:
                      company:
                        id: '129011'
                        type: company
                meta:
                  credits:
                    charged: 1
                  request_id: abc-123
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              examples:
                missing_company_ids:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The 'company_ids' parameter is required.
                too_many_company_ids:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The 'company_ids' parameter accepts up to 100 company IDs.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies/signals:
    post:
      operationId: searchCompaniesSignals
      tags:
        - Companies
        - v1
      summary: Search Company Signals
      description: |-
        Retrieve signals for a specified set of company IDs. The response returns the signals linked to the provided companies.
        Credit Node: You are charged 1 credit per company if the company has signals and there was no active deep data access within the last 12 months. The number of signals returned does not affect credit usage — no additional credits are charged per signal.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                categories:
                  type: array
                  items:
                    type: string
                    enum:
                      - business_expansion
                      - competitive_landscape
                      - event_participation
                      - industry_recognition
                      - leadership_changes
                      - corporate_challenges
                      - mergers_and_acquisitions
                      - customer_acquisition
                      - investment_activity
                      - product_and_service_development
                      - partnerships_and_collaborations
                      - financial_struggles
                      - job_ads
                      - regulatory_compliance_updates
                      - register_updates
                    description: Categories to group similar signals together
                    example: business_expansion
                    x-apidog-enum:
                      - value: business_expansion
                        name: Business Expansion
                        description: Events that indicate the company’s physical and operational growth through new office locations, facility upgrades, or increases in headcount, signalling expansion into new markets.
                      - value: competitive_landscape
                        name: Competitive Landscape
                        description: Events that reflect the competitive environment in which the company operates, including the identification of new or existing rivals that may influence strategic positioning.
                      - value: event_participation
                        name: Event Participation
                        description: Events capturing the company’s active involvement in industry gatherings—such as trade shows, conferences, or exhibitions—to boost brand visibility and create networking opportunities.
                      - value: industry_recognition
                        name: Industry Recognition
                        description: Events where the company or its representatives receive formal accolades or awards, underscoring excellence and leadership within their industry.
                      - value: leadership_changes
                        name: Leadership Changes
                        description: Events that document shifts in the company’s leadership structure, including new hires, promotions, departures, or retirements of key executives.
                      - value: corporate_challenges
                        name: Corporate Challenges
                        description: Events that highlight internal difficulties impacting business performance, including legal disputes, significant workforce reductions, or other operational challenges.
                      - value: mergers_and_acquisitions
                        name: Mergers and Acquisitions
                        description: Events involving major corporate restructuring such as mergers, acquisitions, or asset sales that can fundamentally change the company’s strategic direction.
                      - value: customer_acquisition
                        name: Customer Acquisition
                        description: Events that demonstrate the company’s success in expanding its client base through signing new clients or securing major contracts.
                      - value: investment_activity
                        name: Investment Activity
                        description: Events where the company invests resources in external opportunities—either by investing in other companies or assets, or by securing external financing—to drive growth.
                      - value: product_and_service_development
                        name: Product and Service Development
                        description: Events showcasing the company’s commitment to innovation, including the development of new products, enhancements to existing offerings, or integration of new services.
                      - value: partnerships_and_collaborations
                        name: Partnerships and Collaborations
                        description: Events where the company forms strategic alliances or partnerships with other organisations to leverage shared resources and expand market reach.
                      - value: financial_struggles
                        name: Financial Struggles
                        description: Events that indicate the company is experiencing economic or fiscal challenges, such as declining revenues, increased debt, liquidity issues, or cost-cutting measures.
                      - value: job_ads
                        name: Job Ads
                        description: Events that capture the posting of job openings by a company, reflecting hiring initiatives, workforce expansion, or strategic talent acquisition efforts across various departments and roles.
                      - value: regulatory_compliance_updates
                        name: Regulatory Compliance Updates
                        description: Events that indicate changes, announcements, or actions related to a company’s adherence to legal, regulatory, or industry standards, including new filings, certifications, audits, or compliance measures that impact operational and strategic practices.
                      - value: register_updates
                        name: Register Updates
                        description: Events that reflect changes or additions in official company registries, such as modifications to corporate records, filings with governmental authorities, or updates to ownership and governance information.
                  description: Filter to search for signals in specific categories
                  example:
                    - business_expansion
                    - investment_activity
                company_ids:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
                  description: Array of company IDs to filter signals for (mandatory)
                  example:
                    - '159001425'
                    - '129011'
                publication_date:
                  description: |
                    Filter signals by publication date (YYYY-MM-DD). If both `from` and `to` are provided, `from` must be earlier than or equal to `to`.
                  type: object
                  properties:
                    from:
                      type: string
                      format: date
                      description: Start date for the publication date filter (inclusive)
                      example: '2023-01-01'
                    to:
                      type: string
                      format: date
                      description: End date for the publication date filter (inclusive)
                      example: '2023-12-31'
                event_date:
                  description: |
                    Filter signals by event date (YYYY-MM-DD). If both `from` and `to` are provided, `from` must be earlier than or equal to `to`.
                  type: object
                  properties:
                    from:
                      type: string
                      format: date
                      description: Start date for the event date filter (inclusive)
                      example: '2023-01-01'
                    to:
                      type: string
                      format: date
                      description: End date for the event date filter (inclusive)
                      example: '2023-12-31'
              required:
                - company_ids
              additionalProperties: false
            examples:
              filtered_search:
                summary: Search with category filter
                value:
                  company_ids:
                    - '159001425'
                    - '129011'
                  categories:
                    - business_expansion
                    - investment_activity
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PageCursor'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SignalV1'
                  meta:
                    type: object
                    required:
                      - credits
                      - pagination
                      - request_id
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 0
                      pagination:
                        type: object
                        required:
                          - total_count
                        properties:
                          next_cursor:
                            type:
                              - string
                              - 'null'
                            example: dXNlcjpVMEc5V0ZYTlo
                          total_count:
                            type: integer
                            example: 1450
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Invalid mandatory fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              examples:
                missing_company_ids:
                  value:
                    errors:
                      - code: missing_mandatory_field
                        title: The 'company_ids' field is required and cannot be left empty.
                invalid_parameter:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The 'categories' field must be a valid array of signal categories.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies/search:
    post:
      operationId: searchCompanies
      tags:
        - Companies
        - v1
      summary: Search Companies
      description: |-
        Perform search queries using criteria like name, location, industry, size or filters like `has_phone`.
        Returns matching company IDs and basic company information.
        Credit Note: Searches do not consume credits. Credits are only used if you subsequently retrieve deep data for a company not accessed within the last 12 months.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PageCursor'
        - $ref: '#/components/parameters/PageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                search_terms:
                  type: array
                  items:
                    type: string
                  description: List of strings to match against company name, alternative names, trade name and domain(s).
                  example:
                    - Leadfeeder
                locations:
                  type: array
                  items:
                    type: object
                    properties:
                      street:
                        type: string
                        description: The street name with our without a number.
                        example: Durlacher Allee 73
                      postal_code:
                        type:
                          - string
                          - 'null'
                        description: The postal code related to the company's physical location. The format varies by country.
                        example: '76131'
                      city:
                        type:
                          - string
                          - 'null'
                        description: The city name.
                        example: Karlsruhe
                      country_code:
                        type:
                          - string
                          - 'null'
                        description: This field indicates the country supported for Leadfeeder operations and requires a two letter country code according to ISO 3166 Alpha-2 (see [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
                        example: DE
                      region_code:
                        type:
                          - string
                          - 'null'
                        description: The code for the region. For European companies the NUTS1-3 schema is used. For companies outside of Europe values that comply with ISO 3166-2 with underscores are returned.
                        example: DE1
                      geo:
                        type: object
                        properties:
                          latitude:
                            type:
                              - number
                              - 'null'
                            description: The latitude of the geographical point.
                            example: 49.01
                          longitude:
                            type:
                              - number
                              - 'null'
                            description: The longitude of the geographical point.
                            example: 8.43
                          distance:
                            type: number
                            description: Maximum distance in kilometers from the geographical point described with latitude and longitude. The maximum value that can be used is 500 km.
                            default: 20
                            example: 20
                  description: Search in the company address. Multiple locations can be passed which will be combined as an OR query.
                industries:
                  type: object
                  properties:
                    classification:
                      type: string
                      enum:
                        - wz
                        - nace
                      example: nace
                    codes:
                      type: array
                      items:
                        type: string
                      description: List of codes from the industry classification table. For the full set of valid codes, refer to the NACE/WZ table.
                      examples:
                        - - '62.01'
                        - - '62.01'
                          - '62.02'
                  description: Object specifying industry classification filters (e.g. NACE, WZ, or internal categories).
                employee_ranges:
                  type: array
                  items:
                    type:
                      - string
                      - 'null'
                    enum:
                      - 1-10
                      - 11-100
                      - 101-500
                      - 501-1.000
                      - 1.001-5.000
                      - 5.001-10.000
                      - 10.000+
                      - null
                    description: A range indicator of the approximate headcount for this company.
                    example: 101-500
                  description: List of employee count ranges (e.g. 1-10, 51-200) to filter companies by size.
                  example:
                    - 101-500
                    - 501-1.000
                revenue:
                  type: object
                  properties:
                    min:
                      type: integer
                      example: 1000000
                    max:
                      type: integer
                      example: 5000000
                  description: Defines a revenue range filter for companies. Specify at least one of min or max to set the lower or upper revenue boundary. Negative integer values are not supported.
                icp_ids:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    minLength: 1
                  description: |-
                    List of Ideal Customer Profile (ICP) IDs to use as a filter. The search will return companies that match the criteria of at least one of the referenced ICPs (multiple ICPs are combined using OR).

                    ICP IDs can be retrieved from the **Retrieve Ideal Customer Profiles** endpoint. Unknown or invalid IDs are ignored; if none of the supplied IDs exist or have valid filters, the search returns no results.
                  example:
                    - '6080'
                    - '6081'
                filters:
                  type: object
                  description: Object containing additional boolean filters to refine the search results. All filters are combined using AND.
                  properties:
                    has_phone:
                      type: boolean
                      description: If true, only return companies that have at least one phone number.
                    has_email:
                      type: boolean
                      description: If true, only return companies that have at least one known email address.
                    has_social_media_profiles:
                      type: boolean
                      description: If true, filter for companies with at least one social media profile (LinkedIn, Facebook, etc.).
                    do_not_contact:
                      type: boolean
                      description: If true, only return companies that are marked as not to be contacted. This is typically used for compliance or CRM rules.
                    has_financials_revenue:
                      type: boolean
                      description: If true, only return companies with known revenue data.
                    has_financials_earnings:
                      type: boolean
                      description: If true, only return companies with known earnings data.
                    has_financials_net_worth:
                      type: boolean
                      description: If true, only return companies with known net worth data.
                    has_ip_addresses:
                      type: boolean
                      description: If true, only return companies with ip data.
            examples:
              simple_name_search:
                summary: Simple search by company name
                value:
                  search_terms:
                    - Microsoft
              location_and_industry_search:
                summary: Search by location and industry
                value:
                  locations:
                    - city: London
                      country_code: GB
                  industries:
                    classification: nace
                    codes:
                      - '70.10'
                  employee_ranges:
                    - 11-100
              comprehensive_search:
                summary: Comprehensive search with multiple criteria
                value:
                  search_terms:
                    - leadfeeder.com
                  locations:
                    - city: Karlsruhe
                      country_code: DE
                  industries:
                    classification: nace
                    codes:
                      - '62.01'
                      - '62.02'
                  employee_ranges:
                    - 101-500
                    - 501-1.000
                  revenue:
                    min: 1000000
                  filters:
                    has_phone: true
                    has_email: true
                    has_social_media_profiles: true
                    has_financials_revenue: true
              icp_search:
                summary: Search by Ideal Customer Profile
                description: Return companies matching the saved ICP definitions. The filters of the referenced ICPs are combined using OR.
                value:
                  icp_ids:
                    - '6080'
                    - '6081'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    description: Accounts with an active platform subscription receive `CompanySummaryV1` objects, while those without receive `MaskedCompanySummaryV1` objects.
                    anyOf:
                      - type: array
                        items:
                          $ref: '#/components/schemas/CompanySummaryV1'
                      - type: array
                        items:
                          $ref: '#/components/schemas/MaskedCompanySummaryV1'
                  meta:
                    type: object
                    required:
                      - credits
                      - pagination
                      - request_id
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 0
                      pagination:
                        type: object
                        required:
                          - total_count
                        properties:
                          next_cursor:
                            type:
                              - string
                              - 'null'
                            example: dXNlcjpVMEc5V0ZYTlo
                          total_count:
                            type: integer
                            example: 1450
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Invalid mandatory fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              examples:
                empty_body:
                  value:
                    errors:
                      - code: missing_mandatory_fields
                        title: At least one field in the request body must be provided.
                invalid_parameter:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The search_terms field must be a valid array of strings.
                invalid_icp_ids:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The 'icp_ids' field must be a valid array of ICP IDs.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies/match:
    post:
      operationId: matchCompanies
      tags:
        - Companies
        - v1
      summary: Match Companies
      description: |-
        Find matching companies based on the provided input parameters.
        Returns matching company IDs and basic company information.
        **Important:** Each company object must include at least one of these required fields: `company_name`, `url`, `vat_id`, or `register_id`. Additional fields like email, phone, and address can improve match accuracy but cannot be used alone.
        Credit Note: Matches do not consume credits. Credits are only used if you subsequently retrieve deep data for a company you haven't accessed within the last 12 months.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: max_results_per_company
          in: query
          schema:
            type: number
            default: 5
            minimum: 1
            maximum: 20
          description: Number of maximum results per company match input object
          example: 5
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - companies
              properties:
                companies:
                  type: array
                  items:
                    type: object
                    properties:
                      company_name:
                        type: string
                        example: Dealfront Group GmbH
                        description: The legal name of the company
                      url:
                        type:
                          - string
                          - 'null'
                        description: The URL of the company website.
                        example: https://www.leadfeeder.com/welcome
                      email:
                        type: string
                        description: A standard e-mail address.
                        example: info@leadfeeder.com
                      phone:
                        type: string
                        description: E.164 representation of a phone number.
                        example: +49 721 50057501
                      country:
                        type:
                          - string
                          - 'null'
                        description: The country name.
                        example: Germany
                      country_code:
                        type:
                          - string
                          - 'null'
                        description: This field indicates the country supported for Leadfeeder operations and requires a two letter country code according to ISO 3166 Alpha-2 (see [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
                        example: DE
                      city:
                        type:
                          - string
                          - 'null'
                        description: The city name.
                        example: Karlsruhe
                      postal_code:
                        type:
                          - string
                          - 'null'
                        description: The postal code related to the company's physical location. The format varies by country.
                        example: '76131'
                      street:
                        type: string
                        description: The street name with our without a number.
                        example: Durlacher Allee 73
                      street_name:
                        type:
                          - string
                          - 'null'
                        description: The street name part of the company's primary address.
                        example: Durlacher Allee
                      street_number:
                        type:
                          - string
                          - 'null'
                        description: The street number part of the company's primary address. This field does not necessarily contain a number, values like 1st, 23-35 or 13A are also common.
                        example: '73'
                      register_id:
                        type:
                          - string
                          - 'null'
                        description: The company's registration number from the commercial register.
                        example: HRB711540
                      register_location:
                        type:
                          - string
                          - 'null'
                        description: The company's register location.
                        example: Mannheim
                      vat_id:
                        type:
                          - string
                          - 'null'
                        description: The company's VAT ID (tax ID).
                        example: DE276265194
                    anyOf:
                      - required:
                          - company_name
                      - required:
                          - url
                      - required:
                          - vat_id
                      - required:
                          - register_id
                  minItems: 1
                  maxItems: 200
            examples:
              dealfront_example:
                summary: Company match request example
                value:
                  companies:
                    - company_name: Dealfront Group GmbH
                      url: https://www.dealfront.com/welcome
                      email: info@dealfront.com
                      phone: +49 721 50057501
                      country: Germany
                      country_code: DE
                      city: Karlsruhe
                      postal_code: '76131'
                      street: Durlacher Allee 73
                      street_name: Durlacher Allee
                      street_number: '73'
                      register_id: HRB711540
                      register_location: Mannheim
                      vat_id: DE276265194
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/CompanyMatchV1'
                    description: The results of the match request. This field contains a list of arrays, each containing a list of matching companies as summary objects, along with their match score. The order will be the same as the order of the input objects that were provided when the match request was created.
                  meta:
                    type: object
                    required:
                      - request_id
                      - credits
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                success:
                  value:
                    data:
                      - - type: company_match
                          id: '129011'
                          attributes:
                            match_score: 0.95
                          relationships:
                            company_summary:
                              id: '129011'
                              type: company_summary
                              attributes:
                                name: Dealfront Group GmbH
                                role: group_member
                                register:
                                  status: active
                                meta:
                                  do_not_contact: false
                                  has_updated_id: false
                                  has_ip_addresses: true
                                  has_phones: true
                                  has_fax: false
                                  has_mail: true
                                  has_contacts: true
                                  has_social_accounts: true
                                  has_register_id: true
                                  has_vat_id: true
                                  has_financials_revenue: true
                                  has_financials_earnings: true
                                  has_financials_net_worth: true
                              relationships:
                                group_company:
                                  id: '159001425'
                                  type: company
                        - type: company_match
                          id: '155950504'
                          attributes:
                            match_score: 0.8
                          relationships:
                            company_summary:
                              id: '155950504'
                              type: company_summary
                              attributes:
                                name: Leaxxxxxxx
                                role: group_member
                                register:
                                  status: active
                                meta:
                                  do_not_contact: true
                                  has_updated_id: false
                                  has_ip_addresses: false
                                  has_phones: true
                                  has_fax: true
                                  has_mail: true
                                  has_contacts: false
                                  has_social_accounts: true
                                  has_register_id: true
                                  has_vat_id: true
                                  has_financials_revenue: true
                                  has_financials_earnings: true
                                  has_financials_net_worth: true
                              relationships:
                                group_company: null
                    meta:
                      credits:
                        charged: 0
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Invalid mandatory fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              examples:
                empty_body:
                  value:
                    errors:
                      - code: missing_mandatory_fields
                        title: 'The request body requires at least the following field to be present: ''companies''.'
                invalid_companies:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: 'Each company must have at least one of the following fields required for matching: ''company_name'', ''url'', ''vat_id'', or ''register_id''.'
                invalid_max_results_per_company:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The value of `max_results_per_company` must be a positive integer between 1 and 10.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies/{id}/lists:
    post:
      operationId: addCompanyToLists
      tags:
        - Companies
        - v1
      summary: Add Company to Lists
      description: |-
        Allows the addition of this company to one or more lists. Since lists are a separate entity, the IDs that you must pass in this endpoint come from the **Retrieve Lists** and **Get List Details** endpoints.

        Credit Note: Adding a company to lists does not consume credits.
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: array
                  description: Array of list references to add the company to
                  items:
                    type: object
                    required:
                      - type
                      - id
                    properties:
                      type:
                        type: string
                        enum:
                          - list
                        description: Must be 'list'
                      id:
                        type: string
                        description: The list ID (must be a company list, e.g., 'company_123')
            example:
              data:
                - type: list
                  id: company_123
                - type: list
                  id: company_456
      responses:
        '201':
          description: Company successfully added to lists
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
              example:
                data: null
                meta:
                  request_id: abc123
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The requested list could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    delete:
      operationId: removeCompanyFromLists
      tags:
        - Companies
        - v1
      summary: Remove Company from Lists
      description: |-
        Allows the removal of this company from one or more lists.

        Credit Note: Removing a company from lists does not consume credits.
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: array
                  description: Array of list references to remove the company from
                  items:
                    type: object
                    required:
                      - type
                      - id
                    properties:
                      type:
                        type: string
                        enum:
                          - list
                        description: Must be 'list'
                      id:
                        type: string
                        description: The list ID (must be a company list, e.g., 'company_123')
            example:
              data:
                - type: list
                  id: company_123
                - type: list
                  id: company_456
      responses:
        '200':
          description: Company successfully removed from lists
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
              example:
                data: null
                meta:
                  request_id: abc123
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The requested list could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/companies/{id}/tags:
    post:
      operationId: assignTagsToCompany
      tags:
        - Companies
        - v1
      summary: Assign Tags to Company
      description: |-
        Allows the assignment of one or more tags to a given company. Since tags are a separate entity, the IDs that you must pass in this endpoint come from the **Retrieve Tags** and **Get Tag Details** endpoints.

        Credit Note: Assigning tags to a company does not consume credits.
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: array
                  description: Array of tag references to assign to the company
                  items:
                    type: object
                    required:
                      - type
                      - id
                    properties:
                      type:
                        type: string
                        enum:
                          - tag
                        description: Must be 'tag'
                      id:
                        type: string
                        description: The tag ID
            example:
              data:
                - type: tag
                  id: dd11fc370098e78e
                - type: tag
                  id: 8bb95c4d8e7c5fd2
      responses:
        '201':
          description: Tags successfully assigned to company
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
              example:
                data: null
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    delete:
      operationId: unassignTagsFromCompany
      tags:
        - Companies
        - v1
      summary: Unassign Tags from Company
      description: |-
        Allows the unassignment of one or more tags from a given company.

        Credit Note: Unassigning tags from a company does not consume credits.
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: array
                  description: Array of tag references to unassign from the company
                  items:
                    type: object
                    required:
                      - type
                      - id
                    properties:
                      type:
                        type: string
                        enum:
                          - tag
                        description: Must be 'tag'
                      id:
                        type: string
                        description: The tag ID
            example:
              data:
                - type: tag
                  id: dd11fc370098e78e
                - type: tag
                  id: 8bb95c4d8e7c5fd2
      responses:
        '200':
          description: Tags successfully unassigned from company
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
              example:
                data: null
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/contacts/{id}:
    get:
      operationId: getContact
      tags:
        - Contacts
        - v1
      summary: Get Contact Details
      description: |-
        Get the details of a contact by ID.
        Credit Note: Accessing full deep data consumes 1 credit, unless the contact was already accessed within the last 12 months.
      parameters:
        - $ref: '#/components/parameters/ContactId'
        - $ref: '#/components/parameters/AccountId'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - company
              - lists
              - buyer_personas
              - crm_connections
              - crm_connections.crm_record
              - crm_connections.crm_record.crm_owner
              - crm_suggestions
              - crm_suggestions.crm_record
              - crm_suggestions.crm_record.crm_owner
          description: Specify which additional data should be attached to the result.
          example: company
      responses:
        '200':
          description: Returns the contact details for the specified ID. If `include=company` is supplied, the response includes the company details. If no contact is found for the specified ID, a `404` error is raised.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/ContactV1'
                  meta:
                    type: object
                    required:
                      - request_id
                      - credits
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/contacts:
    get:
      operationId: getContacts
      tags:
        - Contacts
        - v1
      summary: Retrieve Contacts
      description: |-
        Retrieve a list of contacts based on the provided IDs.
        Credit Note: Each company will contain it's full deep data and it will consume 1 credit, unless the company has already been accessed within the last 12 months.
      parameters:
        - $ref: '#/components/parameters/ContactIds'
        - $ref: '#/components/parameters/AccountId'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - company
              - lists
              - buyer_personas
              - crm_connections
              - crm_connections.crm_record
              - crm_connections.crm_record.crm_owner
              - crm_suggestions
              - crm_suggestions.crm_record
              - crm_suggestions.crm_record.crm_owner
          description: Specify which additional data should be attached to the result.
          example: company
      responses:
        '200':
          description: Returns the contact details for the specified IDs. If `include=company` is supplied, the responses include the company details. If no contact is found for a certain ID, the `data` field will not contain an entry for that ID.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactV1'
                  meta:
                    type: object
                    required:
                      - request_id
                      - credits
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Invalid mandatory fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              example:
                errors:
                  - code: bad_request_parameters
                    title: 'Missing required request parameters: [ids]'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/contacts/search:
    post:
      operationId: searchContacts
      tags:
        - Contacts
        - v1
      summary: Search Contacts
      description: |-
        Search for contacts based on the provided search parameters and returns contact summary objects.
        Credit Note: Searches do not consume credits. Credits are only used if you subsequently retrieve deep data for a contact that has not been accessed within the last 12 months.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PageCursor'
        - $ref: '#/components/parameters/PageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                search_terms:
                  type: array
                  items:
                    type: string
                  description: Search in contact fullname and title fields.
                  example:
                    - John Doe
                positions:
                  type: array
                  items:
                    type: string
                  description: Search in orig and en fields
                  example:
                    - CEO
                    - CTO
                emails:
                  type: array
                  items:
                    type: string
                  example:
                    - john.doe@example.com
                company_ids:
                  type: array
                  items:
                    type: string
                    description: The Leadfeeder company ID.
                    example: '129011'
                  example:
                    - '129011'
                    - '159001425'
                departments:
                  type: array
                  items:
                    type: string
                    enum:
                      - management_department
                      - unknown_department
                      - sales_department
                      - it_department
                      - business_project_management_department
                      - finance_controlling_department
                      - engineering_department
                      - hr_department
                      - marketing_department
                      - consulting_department
                      - media_communications_department
                      - support_department
                      - rd_department
                      - students_apprentices
                      - production_department
                      - logistics_department
                      - legal_compliance_department
                      - qm_department
                      - product_department
                      - purchasing_department
                  description: The departments the contact works in within the company.
                  example:
                    - marketing_department
                    - students_apprentices
                  x-apidog-enum:
                    - value: management_department
                      name: Management Department
                    - value: unknown_department
                      name: Unknown Department
                    - value: sales_department
                      name: Sales Department
                    - value: it_department
                      name: IT Department
                    - value: business_project_management_department
                      name: Business Project Management Department
                    - value: finance_controlling_department
                      name: Finance Controlling Department
                    - value: engineering_department
                      name: Engineering Department
                    - value: hr_department
                      name: HR Department
                    - value: marketing_department
                      name: Marketing Department
                    - value: consulting_department
                      name: Consulting Department
                    - value: media_communications_department
                      name: Media Communications Department
                    - value: support_department
                      name: Support Department
                    - value: rd_department
                      name: RD Department
                    - value: students_apprentices
                      name: Students Apprentices
                    - value: production_department
                      name: Production Department
                    - value: logistics_department
                      name: Logistics Department
                    - value: legal_compliance_department
                      name: Legal Compliance Department
                    - value: qm_department
                      name: QM Department
                    - value: product_department
                      name: Product Department
                    - value: purchasing_department
                      name: Purchasing Department
                hierarchy_levels:
                  type: array
                  items:
                    type:
                      - string
                      - 'null'
                    enum:
                      - employees
                      - top_management
                      - middle_management
                      - unknown_hierarchy
                      - null
                    description: The hierarchy level the contact has in the company.
                    example: employees
                  example:
                    - top_management
                    - middle_management
                affiliation:
                  type:
                    - string
                    - 'null'
                  enum:
                    - employee
                    - group_employee
                    - related
                  description: Determines how the contact is related to the company.
                  example: employee
                  x-apidog-enum:
                    - value: employee
                      name: Employee
                      description: The contact is an employee of the company.
                    - value: group_employee
                      name: Group employee
                      description: The contact works for some organization in the same company group.
                    - value: related
                      name: Related
                      description: The contact has some relation to the company.
                buyer_persona_ids:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    minLength: 1
                  description: |-
                    List of buyer persona IDs to use as a filter. The search will return contacts that match the criteria of at least one of the referenced buyer personas (multiple personas are combined using OR).

                    Buyer persona IDs can be retrieved from the **Retrieve Buyer Personas** endpoint. Unknown or invalid IDs are ignored; if none of the supplied IDs exist or have valid filters, the search returns no results.
                  example:
                    - '7421'
                    - '7422'
                filters:
                  type: object
                  description: Filter down search results (combined with AND).
                  properties:
                    has_phones:
                      type: boolean
                    has_email:
                      type: boolean
                    has_social_media_profiles:
                      type: boolean
            examples:
              basic_name_search:
                summary: Search by contact name
                description: Simple search for contacts by name
                value:
                  search_terms:
                    - John Smith
              position_and_company_search:
                summary: Search by position within specific companies
                description: Find CEOs and CTOs in specific companies
                value:
                  positions:
                    - CEO
                    - CTO
                  company_ids:
                    - '159001425'
                    - '129011'
              comprehensive_search:
                summary: Comprehensive search with filters
                description: Search with multiple criteria and filters
                value:
                  search_terms:
                    - John Smith
                  departments:
                    - marketing_department
                  hierarchy_levels:
                    - top_management
                    - middle_management
                  filters:
                    has_email: true
                    has_phones: true
              email_search:
                summary: Search by email domain
                description: Find contacts with specific email addresses
                value:
                  emails:
                    - kevin.mcintyre@leadfeeder.com
                    - markus.blaser@siemens.com
                  filters:
                    has_social_media_profiles: true
              buyer_persona_search:
                summary: Search by buyer persona
                description: Return contacts matching the saved buyer persona definitions. The filters of the referenced buyer personas are combined using OR.
                value:
                  buyer_persona_ids:
                    - '7421'
                    - '7422'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    description: Accounts with an active platform subscription receive `ContactSummaryV1` objects, while those without receive `MaskedContactSummaryV1` objects.
                    anyOf:
                      - type: array
                        items:
                          $ref: '#/components/schemas/ContactSummaryV1'
                      - type: array
                        items:
                          $ref: '#/components/schemas/MaskedContactSummaryV1'
                  meta:
                    type: object
                    required:
                      - credits
                      - pagination
                      - request_id
                    properties:
                      credits:
                        type: object
                        required:
                          - charged
                        properties:
                          charged:
                            type: number
                            description: How many credits were consumed for this request.
                            example: 0
                      pagination:
                        type: object
                        required:
                          - total_count
                        properties:
                          next_cursor:
                            type:
                              - string
                              - 'null'
                            example: dXNlcjpVMEc5V0ZYTlo
                          total_count:
                            type: integer
                            example: 1450
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Invalid mandatory fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              examples:
                empty_body:
                  value:
                    errors:
                      - code: missing_mandatory_fields
                        title: At least one field in the request body must be provided.
                invalid_parameter:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The search_terms field must be a valid array of strings.
                invalid_buyer_persona_ids:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The 'buyer_persona_ids' field must be a valid array of buyer persona IDs.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/contacts/{id}/lists:
    post:
      operationId: addContactToLists
      tags:
        - Contacts
        - v1
      summary: Add Contact to Lists
      description: |-
        Allows the addition of this contact to one or more lists. Since lists are a separate entity, the IDs that you must pass in this endpoint come from the **Retrieve Lists** and **Get List Details** endpoints.

        Credit Note: Adding a contact to lists does not consume credits.
      parameters:
        - $ref: '#/components/parameters/ContactId'
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: array
                  description: Array of list references to add the contact to
                  items:
                    type: object
                    required:
                      - type
                      - id
                    properties:
                      type:
                        type: string
                        enum:
                          - list
                        description: Must be 'list'
                      id:
                        type: string
                        description: The list ID (must be a contact list, e.g., 'contact_123')
            example:
              data:
                - type: list
                  id: contact_123
                - type: list
                  id: contact_456
      responses:
        '201':
          description: Contact successfully added to lists
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
              example:
                data: null
                meta:
                  request_id: abc123
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The requested list could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    delete:
      operationId: removeContactFromLists
      tags:
        - Contacts
        - v1
      summary: Remove Contact from Lists
      description: |-
        Allows the removal of this contact from one or more lists.

        Credit Note: Removing a contact from lists does not consume credits.
      parameters:
        - $ref: '#/components/parameters/ContactId'
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: array
                  description: Array of list references to remove the contact from
                  items:
                    type: object
                    required:
                      - type
                      - id
                    properties:
                      type:
                        type: string
                        enum:
                          - list
                        description: Must be 'list'
                      id:
                        type: string
                        description: The list ID (must be a contact list, e.g., 'contact_123')
            example:
              data:
                - type: list
                  id: contact_123
                - type: list
                  id: contact_456
      responses:
        '200':
          description: Contact successfully removed from lists
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
              example:
                data: null
                meta:
                  request_id: abc123
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The requested list could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/lists:
    get:
      operationId: getLists
      tags:
        - Lists
        - v1
      summary: Retrieve Lists
      description: |-
        Retrieve all lists available in the account.
        The response includes each list's attributes and can be filtered through query parameters.

        Credit Note: Retrieving list definitions does not consume credits.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/ScopeRequired'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ListV1'
                  meta:
                    type: object
                    required:
                      - pagination
                      - request_id
                    properties:
                      pagination:
                        type: object
                        required:
                          - page_num
                          - page_count
                          - total_count
                        properties:
                          page_num:
                            type: integer
                            example: 1
                          page_count:
                            type: integer
                            example: 1
                          total_count:
                            type: integer
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    post:
      operationId: createList
      tags:
        - Lists
        - v1
      summary: Create a List
      description: Create a new list in the account.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: object
                  required:
                    - type
                    - attributes
                  properties:
                    type:
                      type: string
                      default: list
                    attributes:
                      type: object
                      required:
                        - name
                        - scope
                      properties:
                        name:
                          type: string
                          description: The name of the list
                        scope:
                          type: string
                          description: The scope type of the list
                          enum:
                            - company
                            - contact
            example:
              data:
                type: list
                attributes:
                  name: US Prospects
                  scope: company
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/ListV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/lists/{id}:
    get:
      operationId: getList
      tags:
        - Lists
        - v1
      summary: Get List Details
      description: |-
        Retrieve the details of a specific list using its unique ID.
        The response includes the list's attributes, such as its name and scope, along with any related information requested through query parameters. This endpoint is used to fetch the full definition of a list before viewing, updating, or managing its assigned items.

        Credit Note: Retrieving list definitions does not consume credits.
      parameters:
        - name: id
          in: path
          description: The list ID
          required: true
          schema:
            type: string
          example: company_123
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/ListV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    patch:
      operationId: updateList
      tags:
        - Lists
        - v1
      summary: Update List
      description: |-
        Update the name of a list.

        Credit Note: Updating list name does not consume credits.
      parameters:
        - name: id
          in: path
          description: The list ID
          required: true
          schema:
            type: string
          example: company_123
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: object
                  required:
                    - type
                    - attributes
                  properties:
                    type:
                      type: string
                      default: list
                    attributes:
                      type: object
                      required:
                        - name
                      properties:
                        name:
                          type: string
                          description: The new name of the list
            example:
              data:
                type: list
                attributes:
                  name: Updated List Name
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/ListV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    delete:
      operationId: deleteList
      tags:
        - Lists
        - v1
      summary: Delete List
      description: |-
        Delete a list from the account.
        Once removed, the list will no longer be accessible.

        Credit Note: Deleting list does not consume credits.
      parameters:
        - name: id
          in: path
          description: The list ID
          required: true
          schema:
            type: string
          example: company_123
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data: null
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/custom-fields:
    get:
      operationId: getCustomFields
      tags:
        - Custom Fields
        - v1
      summary: Retrieve Custom Fields
      description: |-
        Retrieve the list of all custom field definitions available in the account.
        The response includes each field's attributes.

        Credit Note: Retrieving custom field definitions does not consume credits.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/ScopeOptional'
        - $ref: '#/components/parameters/FieldTypeOptional'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomFieldV1'
                  meta:
                    type: object
                    required:
                      - pagination
                      - request_id
                    properties:
                      pagination:
                        type: object
                        required:
                          - page_num
                          - page_count
                          - total_count
                        properties:
                          page_num:
                            type: integer
                            example: 1
                          page_count:
                            type: integer
                            example: 1
                          total_count:
                            type: integer
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    post:
      operationId: createCustomField
      tags:
        - Custom Fields
        - v1
      summary: Create Custom Field
      description: Create a new custom field in the account.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: object
                  required:
                    - type
                    - attributes
                  properties:
                    type:
                      type: string
                      default: custom_field
                    attributes:
                      type: object
                      required:
                        - name
                        - type
                        - scope
                      properties:
                        name:
                          type: string
                          description: The name of the custom field
                        type:
                          type: string
                          description: The data type of the custom field. For AI types (`ai_score`, `ai_text`, `ai_number`, `ai_boolean`), the `configuration` attribute with a `prompt` is required. For `contact_collection`, `configuration` is optional. For simple types (`text`, `number`, `boolean`, `date`), `configuration` is silently ignored.
                          enum:
                            - text
                            - number
                            - boolean
                            - date
                            - contact_collection
                            - ai_score
                            - ai_text
                            - ai_number
                            - ai_boolean
                        scope:
                          type: string
                          description: Specifies whether the custom field will be applied to companies or contacts
                          enum:
                            - company
                            - contact
                        configuration:
                          allOf:
                            - description: Configuration for AI and contact_collection field types. Must be a JSON object. Silently ignored for simple field types (`text`, `number`, `boolean`, `date`).
                              oneOf:
                                - title: AI configuration
                                  type: object
                                  description: Configuration for AI field types. The `prompt` property is required.
                                  additionalProperties: false
                                  required:
                                    - prompt
                                  properties:
                                    prompt:
                                      type: string
                                      description: The AI prompt text.
                                    prompt_category:
                                      type: string
                                      description: Optional topical category for the AI prompt. Constrains the prompt to a known group used by xenon to organize prompts across the system.
                                      enum:
                                        - job_listings
                                        - news
                                        - funding
                                        - growth
                                        - technologies
                                        - legal_compliance
                                        - marketing
                                        - leadership_changes
                                        - research_and_development
                                        - products
                                      example: technologies
                                    prompt_with_external_data:
                                      type: boolean
                                      description: Whether the AI prompt should use external data.
                                - title: Contact collection configuration
                                  type: object
                                  description: Configuration for contact_collection field type. All properties are optional. contacts_to_enrich cannot exceed num_contacts_max_per_company.
                                  additionalProperties: false
                                  properties:
                                    buyer_persona_id:
                                      type: string
                                      description: Buyer persona identifier used to scope contact discovery (max 50 characters).
                                      maxLength: 50
                                    num_contacts_max_per_company:
                                      type: integer
                                      description: Maximum contacts per company
                                    find_more_contacts_details:
                                      type: boolean
                                      description: Enable Company Contacts Reveal (CCR) enrichment
                                    contacts_to_enrich:
                                      type: integer
                                      description: Number of contacts to enrich; required when find_more_contacts_details is true; cannot exceed num_contacts_max_per_company
                                      minimum: 1
                                    enrich_emails:
                                      type: boolean
                                      description: Include email enrichment in CCR
                                    enrich_phones:
                                      type: boolean
                                      description: Include phone enrichment in CCR
                            - description: |-
                                For AI field types (`ai_score`, `ai_text`, `ai_number`, `ai_boolean`): required, and must include `prompt`.

                                For `contact_collection`: optional, all properties are optional.
            examples:
              simple:
                summary: Simple text field
                value:
                  data:
                    type: custom_field
                    attributes:
                      name: Prospect Status
                      type: text
                      scope: company
              ai_field:
                summary: AI score field with configuration
                value:
                  data:
                    type: custom_field
                    attributes:
                      name: Lead Score
                      type: ai_score
                      scope: company
                      configuration:
                        prompt: Score this lead from 1-100
                        prompt_category: technologies
                        prompt_with_external_data: false
              contact_collection:
                summary: Contact collection field
                value:
                  data:
                    type: custom_field
                    attributes:
                      name: Key Decision Makers
                      type: contact_collection
                      scope: company
                      configuration:
                        num_contacts_max_per_company: 5
                        find_more_contacts_details: true
                        contacts_to_enrich: 3
                        enrich_emails: true
                        enrich_phones: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/CustomFieldV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/custom-fields/{id}:
    get:
      operationId: getCustomField
      tags:
        - Custom Fields
        - v1
      summary: Get Custom Field Details
      description: |-
        Fetch the details of a specific custom field using its internal name.
        The response returns the field's attributes.

        Credit Note: Retrieving custom field definitions does not consume credits.
      parameters:
        - name: id
          in: path
          description: The custom field internal name.
          required: true
          schema:
            type: string
          example: score
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/CustomFieldV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    patch:
      operationId: updateCustomField
      tags:
        - Custom Fields
        - v1
      summary: Update Custom Field
      description: |-
        Update an existing custom field's name and/or configuration.

        At least one of `name` or `configuration` must be provided. If `name` is present, it must not be blank.
        The `configuration` attribute is only meaningful for prompt-capable field types
        (`ai_score`, `ai_text`, `ai_number`, `ai_boolean`, `contact_collection`);
        it is silently ignored for simple types (`text`, `number`, `boolean`, `date`).

        Credit Note: Updating custom fields does not consume credits.
      parameters:
        - name: id
          in: path
          description: The custom field internal name.
          required: true
          schema:
            type: string
          example: score
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: object
                  required:
                    - type
                    - attributes
                  properties:
                    type:
                      type: string
                      default: custom_field
                    attributes:
                      type: object
                      description: At least one of `name` or `configuration` must be provided.
                      properties:
                        name:
                          type: string
                          description: The new name of the custom field. Must not be blank if provided.
                        configuration:
                          description: Configuration for AI and contact_collection field types. Must be a JSON object. Silently ignored for simple field types (`text`, `number`, `boolean`, `date`).
                          oneOf:
                            - title: AI configuration
                              type: object
                              description: Configuration for AI field types. The `prompt` property is required.
                              additionalProperties: false
                              required:
                                - prompt
                              properties:
                                prompt:
                                  type: string
                                  description: The AI prompt text.
                                prompt_category:
                                  type: string
                                  description: Optional topical category for the AI prompt. Constrains the prompt to a known group used by xenon to organize prompts across the system.
                                  enum:
                                    - job_listings
                                    - news
                                    - funding
                                    - growth
                                    - technologies
                                    - legal_compliance
                                    - marketing
                                    - leadership_changes
                                    - research_and_development
                                    - products
                                  example: technologies
                                prompt_with_external_data:
                                  type: boolean
                                  description: Whether the AI prompt should use external data.
                            - title: Contact collection configuration
                              type: object
                              description: Configuration for contact_collection field type. All properties are optional. contacts_to_enrich cannot exceed num_contacts_max_per_company.
                              additionalProperties: false
                              properties:
                                buyer_persona_id:
                                  type: string
                                  description: Buyer persona identifier used to scope contact discovery (max 50 characters).
                                  maxLength: 50
                                num_contacts_max_per_company:
                                  type: integer
                                  description: Maximum contacts per company
                                find_more_contacts_details:
                                  type: boolean
                                  description: Enable Company Contacts Reveal (CCR) enrichment
                                contacts_to_enrich:
                                  type: integer
                                  description: Number of contacts to enrich; required when find_more_contacts_details is true; cannot exceed num_contacts_max_per_company
                                  minimum: 1
                                enrich_emails:
                                  type: boolean
                                  description: Include email enrichment in CCR
                                enrich_phones:
                                  type: boolean
                                  description: Include phone enrichment in CCR
            examples:
              rename:
                summary: Rename a custom field
                value:
                  data:
                    type: custom_field
                    attributes:
                      name: Updated Field Name
              update_configuration:
                summary: Update AI field configuration
                value:
                  data:
                    type: custom_field
                    attributes:
                      configuration:
                        prompt: Updated prompt text
                        prompt_category: technologies
                        prompt_with_external_data: false
              update_both:
                summary: Update name and configuration
                value:
                  data:
                    type: custom_field
                    attributes:
                      name: Renamed AI Field
                      configuration:
                        prompt: New prompt
                        prompt_with_external_data: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/CustomFieldV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    delete:
      operationId: deleteCustomField
      tags:
        - Custom Fields
        - v1
      summary: Delete Custom Field
      description: |-
        Delete a custom field from the account.
        Once removed, the custom field will no longer be accessible.

        Credit Note: Deleting custom fields does not consume credits.
      parameters:
        - name: id
          in: path
          description: The custom field internal name.
          required: true
          schema:
            type: string
          example: '10172'
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data: null
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/tags:
    get:
      operationId: getTags
      tags:
        - Tags
        - v1
      summary: Retrieve Tags
      description: |-
        Retrieve the list of all tags available in the account.
        The response contains all tag definitions, including their identifiers, display names, and colors, which can be used to classify or filter companies within the platform.
        Credit Note: Retrieving tag data does not consume credits.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TagV1'
                  meta:
                    type: object
                    required:
                      - pagination
                      - request_id
                    properties:
                      pagination:
                        type: object
                        required:
                          - page_num
                          - page_count
                          - total_count
                        properties:
                          page_num:
                            type: integer
                            example: 1
                          page_count:
                            type: integer
                            example: 1
                          total_count:
                            type: integer
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  - type: tag
                    id: 4b7e2c9f
                    attributes:
                      name: Prospects
                      color: 0
                      created_at: '2024-12-10T15:57:25Z'
                      updated_at: '2024-11-24T11:50:00Z'
                    relationships:
                      created_by:
                        id: abc123
                        type: user
                meta:
                  pagination:
                    page_num: 1
                    page_count: 1
                    total_count: 1
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    post:
      operationId: createTag
      tags:
        - Tags
        - v1
      summary: Create Tag
      description: |-
        Create a new tag with the provided attributes.
        This endpoint allows clients to define a new tag that can be assigned to companies. The response returns the full tag object, including its generated identifier and timestamps.
        Credit Note: Creating tags doe not consume credits.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: object
                  required:
                    - type
                    - attributes
                  properties:
                    type:
                      type: string
                      default: tag
                    attributes:
                      type: object
                      required:
                        - name
                        - color
                      properties:
                        name:
                          type: string
                          description: The name of the tag
                        color:
                          type: integer
                          description: List of supported color codes
                          enum:
                            - 0
                            - 1
                            - 2
                            - 3
                            - 4
                            - 5
                            - 6
                            - 7
                            - 8
                            - 9
                          x-apidog-enum:
                            - value: 0
                              name: '#1B70F0'
                            - value: 1
                              name: '#08A360'
                            - value: 2
                              name: '#AE540D'
                            - value: 3
                              name: '#D42422'
                            - value: 4
                              name: '#5A219B'
                            - value: 5
                              name: '#073572'
                            - value: 6
                              name: '#00838F'
                            - value: 7
                              name: '#D42422'
                            - value: 8
                              name: '#B61A5C'
                            - value: 9
                              name: '#4C3AED'
            example:
              data:
                type: tag
                attributes:
                  name: US Prospects
                  color: 2
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/TagV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  type: tag
                  id: 4b7e2c9f
                  attributes:
                    name: Prospects
                    color: 0
                    created_at: '2024-12-10T15:57:25Z'
                    updated_at: '2024-11-24T11:50:00Z'
                  relationships:
                    created_by:
                      id: abc123
                      type: user
                meta:
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/tags/{id}:
    get:
      operationId: getTag
      tags:
        - Tags
        - v1
      summary: Get Tag Details
      description: |-
        Fetch the details of a specific tag using its unique tag ID.
        Returns the tag’s attributes, including its name, color, and timestamps indicating when it was created and last updated.
        Credit Note: Retrieving tag data does not consume credits.
      parameters:
        - $ref: '#/components/parameters/TagId'
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/TagV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  type: tag
                  id: 4b7e2c9f
                  attributes:
                    name: Prospects
                    color: 0
                    created_at: '2024-12-10T15:57:25Z'
                    updated_at: '2024-11-24T11:50:00Z'
                  relationships:
                    created_by:
                      id: abc123
                      type: user
                meta:
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    patch:
      operationId: updateTag
      tags:
        - Tags
        - v1
      summary: Update Tag
      description: |-
        Update the attributes of a specific tag identified by its ID.

        This endpoint applies a partial update to a single tag.
        Only the fields provided in the request body will be modified; all other fields remain unchanged.

        Credit Note: Updating tags does not consume credits.
      parameters:
        - $ref: '#/components/parameters/TagId'
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: object
                  required:
                    - type
                    - attributes
                  properties:
                    type:
                      type: string
                      default: tag
                    attributes:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The new name of the tag
                        color:
                          type: integer
                          description: List of supported color codes
                          enum:
                            - 0
                            - 1
                            - 2
                            - 3
                            - 4
                            - 5
                            - 6
                            - 7
                            - 8
                            - 9
                          x-apidog-enum:
                            - value: 0
                              name: '#1B70F0'
                            - value: 1
                              name: '#08A360'
                            - value: 2
                              name: '#AE540D'
                            - value: 3
                              name: '#D42422'
                            - value: 4
                              name: '#5A219B'
                            - value: 5
                              name: '#073572'
                            - value: 6
                              name: '#00838F'
                            - value: 7
                              name: '#D42422'
                            - value: 8
                              name: '#B61A5C'
                            - value: 9
                              name: '#4C3AED'
            example:
              data:
                type: tag
                attributes:
                  name: Updated Tag Name
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/TagV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  type: tag
                  id: 4b7e2c9f
                  attributes:
                    name: Prospects
                    color: 0
                    created_at: '2024-12-10T15:57:25Z'
                    updated_at: '2024-11-24T11:50:00Z'
                  relationships:
                    created_by:
                      id: abc123
                      type: user
                meta:
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    delete:
      operationId: deleteTag
      tags:
        - Tags
        - v1
      summary: Delete Tag
      description: |-
        Delete a specific tag identified by its ID

        Removes the tag from the account and unassigns it from all associated companies.
        Once deleted, the tag cannot be recovered.

        Credit Note: Deleting tags does not consume credits.
      parameters:
        - $ref: '#/components/parameters/TagId'
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data: null
                meta:
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/icps:
    get:
      operationId: getIcps
      tags:
        - Ideal Customer Profiles
        - v1
      summary: Retrieve Ideal Customer Profiles
      description: |-
        Retrieve all Ideal Customer Profiles (ICPs) defined in the account. Each ICP is a saved set of company-level filter criteria (employee count, industry, location) used to identify target companies.

        Credit Note: Retrieving ICP definitions does not consume credits.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ICPV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  - type: icp
                    id: '6080'
                    attributes:
                      name: US Tech Companies
                      created_at: '2024-12-10T15:57:25Z'
                      filters:
                        employee_count:
                          - search_value: 101-500
                            display_value: 101-500 employees
                            negated: false
                        industries:
                          - search_value: '1594_6'
                            display_value: Software Development
                            negated: false
                        location:
                          - search_value: US
                            display_value: United States
                            negated: false
                  - type: icp
                    id: '6081'
                    attributes:
                      name: European ICPs
                      created_at: '2024-11-05T10:30:00Z'
                      filters:
                        employee_count:
                          - search_value: 11-50
                            display_value: 11-50 employees
                            negated: false
                        location:
                          - search_value: DE
                            display_value: Germany
                            negated: false
                meta:
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/icps/{id}:
    get:
      operationId: getIcp
      tags:
        - Ideal Customer Profiles
        - v1
      summary: Get Ideal Customer Profile Details
      description: |-
        Get the details of a specific Ideal Customer Profile (ICP) by ID, including its name, creation timestamp, and the full set of filter criteria that define it.

        Credit Note: Retrieving an ICP definition does not consume credits.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The ICP ID.
          example: '6080'
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/ICPV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  type: icp
                  id: '6080'
                  attributes:
                    name: US Tech Companies
                    created_at: '2024-12-10T15:57:25Z'
                    filters:
                      employee_count:
                        - search_value: 101-500
                          display_value: 101-500 employees
                          negated: false
                      industries:
                        - search_value: '1594_6'
                          display_value: Software Development
                          negated: false
                      location:
                        - search_value: US
                          display_value: United States
                          negated: false
                meta:
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/buyer-personas:
    get:
      operationId: getBuyerPersonas
      tags:
        - Buyer Personas
        - v1
      summary: Retrieve Buyer Personas
      description: |-
        Retrieve all buyer personas defined in the account. Each buyer persona is a saved set of contact-level filter criteria (department, job title, location, seniority) used to identify target contacts.

        Credit Note: Retrieving buyer persona definitions does not consume credits.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BuyerPersonaV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  - type: buyer_persona
                    id: '7421'
                    attributes:
                      name: Sales Managers
                      created_at: '2024-12-10T15:57:25Z'
                      filters:
                        department:
                          - search_value: sales
                            display_value: Sales
                            negated: false
                        job_title:
                          - search_value: Manager
                            display_value: Manager
                            negated: false
                        seniority:
                          - search_value: director
                            display_value: Director
                            negated: false
                          - search_value: vp
                            display_value: VP
                            negated: false
                        location:
                          - search_value: US
                            display_value: United States
                            negated: false
                  - type: buyer_persona
                    id: '7422'
                    attributes:
                      name: IT Directors
                      created_at: '2024-11-05T10:30:00Z'
                      filters:
                        department:
                          - search_value: IT
                            display_value: Information Technology
                            negated: false
                        job_title:
                          - search_value: Director
                            display_value: Director
                            negated: false
                        seniority:
                          - search_value: c_level
                            display_value: C Level
                            negated: false
                meta:
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/buyer-personas/{id}:
    get:
      operationId: getBuyerPersona
      tags:
        - Buyer Personas
        - v1
      summary: Get Buyer Persona Details
      description: |-
        Get the details of a specific buyer persona by ID, including its name, creation timestamp, and the full set of filter criteria that define it.

        Credit Note: Retrieving a buyer persona definition does not consume credits.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The buyer persona ID.
          example: '7421'
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/BuyerPersonaV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  type: buyer_persona
                  id: '7421'
                  attributes:
                    name: Sales Managers
                    created_at: '2024-12-10T15:57:25Z'
                    filters:
                      department:
                        - search_value: sales
                          display_value: Sales
                          negated: false
                      job_title:
                        - search_value: Manager
                          display_value: Manager
                          negated: false
                      seniority:
                        - search_value: director
                          display_value: Director
                          negated: false
                        - search_value: vp
                          display_value: VP
                          negated: false
                      location:
                        - search_value: US
                          display_value: United States
                          negated: true
                meta:
                  request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/ip/enrich:
    get:
      operationId: enrichIp
      tags:
        - IP
        - v1
      summary: Enrich Company IP Address
      description: |-
        Enriches an input IP (IPv4/IPv6) with matching company information (if any).
        **Note:**
        - This endpoint requires an active subscription to the IP Enrich product.
        - A request will only be counted as a successful match when the `company_type` attribute is set to `company`.
      parameters:
        - $ref: '#/components/parameters/Ip'
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/EnrichedIpV1'
                  meta:
                    type: object
                    required:
                      - num_results
                      - request_id
                    properties:
                      num_results:
                        type: integer
                        description: Set to 1 if the request is considered successful. Otherwise, it is set to 0.
                        example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Invalid mandatory fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              examples:
                invalid_parameter:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The `ip` query parameter is required and must be a valid IPv4 or IPv6 address
                no_subscription:
                  value:
                    errors:
                      - code: missing_subscription
                        title: The account 12345 doesn't have a valid subscription to use the IP enrich endpoint
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/usage:
    get:
      operationId: usage
      tags:
        - Usage
        - v1
      summary: Get Endpoints Usage
      description: |
        Access usage statistics for various API endpoints for monitoring and auditing purposes.
        Returns usage data for all endpoints accessible by the requesting account within the specified date range.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: start_period
          in: query
          required: true
          schema:
            type: string
            pattern: ^\d{4}-\d{2}$
          description: The starting month for the usage period, formatted as YYYY-MM
          example: 2025-01
        - name: end_period
          in: query
          required: true
          schema:
            type: string
            pattern: ^\d{4}-\d{2}$
          description: The ending month for the usage period, formatted as YYYY-MM. Must be greater than or equal to start_period.
          example: 2026-01
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiUsageV1'
                  meta:
                    type: object
                    required:
                      - total_records
                      - request_id
                    properties:
                      total_records:
                        type: integer
                        description: The total number of records in the response.
                        example: 100
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data:
                  - type: api_usage
                    id: 2025-01_companies/search_POST
                    attributes:
                      period: 2025-01
                      endpoint_path: /companies/search
                      http_method: POST
                      num_requests: 10
                      num_failed_requests: 1
                      num_successful_requests: 5
                      num_returned_entities: 100
                  - type: api_usage
                    id: 2025-03_companies_GET
                    attributes:
                      period: 2025-03
                      endpoint_path: /companies
                      http_method: GET
                      num_requests: 25
                      num_failed_requests: 1
                      num_successful_requests: 24
                      num_returned_entities: 48
                meta:
                  total_records: 2
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Invalid parameters or validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
              examples:
                empty_body:
                  value:
                    errors:
                      - code: missing_mandatory_fields
                        title: At least one field in the request body must be provided.
                invalid_parameter:
                  value:
                    errors:
                      - code: invalid_parameter
                        title: The search_terms field must be a valid array of strings.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/web-visits:
    post:
      operationId: searchWebVisits
      tags:
        - Web Visits
        - v1
      summary: Search Web Visits
      description: Search for web visits within a date range. Returns a paginated list of visit records including engagement data, visitor information, and location.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - company
          description: Specify which additional data should be attached to the result.
          example: company
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - start_date
                - end_date
              properties:
                start_date:
                  type: string
                  format: date
                  description: The start of the date range to search (inclusive). Must be a valid ISO 8601 date.
                  example: '2026-01-01'
                end_date:
                  type: string
                  format: date
                  description: The end of the date range to search (inclusive). Must be a valid ISO 8601 date.
                  example: '2026-01-31'
                filters:
                  type: object
                  properties:
                    company_id:
                      type: string
                      description: Filter visits by company ID.
                      example: abc123
                    location_cities:
                      type: array
                      items:
                        type: string
                      description: Filter visits by city names.
                      example:
                        - Munich
                        - Berlin
                    location_country_codes:
                      type: array
                      items:
                        type: string
                      description: Filter visits by ISO 3166-1 alpha-2 country codes.
                      example:
                        - DE
                        - AT
            examples:
              basic_search:
                summary: Basic date range search
                description: Search all web visits within a date range
                value:
                  start_date: '2026-01-01'
                  end_date: '2026-01-31'
              company_search:
                summary: Search visits for a specific company
                description: Search visits associated with a specific company
                value:
                  start_date: '2026-01-01'
                  end_date: '2026-01-31'
                  filters:
                    company_id: '159001425'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebVisitV1'
                  meta:
                    type: object
                    required:
                      - pagination
                      - request_id
                    properties:
                      pagination:
                        type: object
                        required:
                          - page_num
                          - page_count
                          - total_count
                        properties:
                          page_num:
                            type: integer
                            example: 1
                          page_count:
                            type: integer
                            example: 1
                          total_count:
                            type: integer
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                webVisits:
                  summary: A list of web visits
                  value:
                    data:
                      - type: web_visit
                        id: 5b4f313e-46de-11e8-b981-05bebed8e58b
                        attributes:
                          started_at: '2026-01-15T10:30:00.000Z'
                          source: google
                          medium: cpc
                          campaign: Homepage Split
                          referring_url: https://www.google.com/search?q=leadfeeder
                          keyword: website leads
                          landing_page_path: /home
                          page_depth: 4
                          visit_length: 80
                          device_type: smartphone
                          identifiers:
                            lf_client_id: LF1.1.a3f8b2d1e4c90123.1742597607000
                            ga_client_ids:
                              - '5829104736.1742616961'
                            adobe_cookies: []
                          visitor:
                            email: null
                            first_name: null
                            last_name: null
                          engagements:
                            - hostname: www.leadfeeder.com
                              page:
                                path: /pricing/
                                title: Pricing for all stages of growth
                                url: http://www.leadfeeder.com/pricing/
                              previous_page_path: (entrance)
                              has_met_goals: false
                              event_type: page-view
                              time_on_page: 22
                        relationships:
                          location:
                            type: location
                            id: 6xeTMh2VfiAzFd86n7GNJ3
                            attributes:
                              country: Finland
                              country_code: FI
                              region: Uusimaa
                              region_code: FI-18
                              city: Helsinki
                              geonames_id: '658225'
                              state_code: FI-18
                          company:
                            id: '129011'
                            type: company
                    meta:
                      pagination:
                        page_num: 1
                        page_count: 1
                        total_count: 1
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/web-visits/custom-feeds:
    get:
      operationId: getWebVisitsCustomFeeds
      tags:
        - Web Visits
        - v1
      summary: Retrieve Custom Feeds
      description: Retrieve all custom feeds accessible to the current user for the given account.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - folder
          description: Specify which additional data should be attached to the result.
          example: folder
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomFeedV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                customFeeds:
                  summary: A list of custom feeds
                  value:
                    data:
                      - type: custom_feed
                        id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        attributes:
                          name: All companies
                          created_at: '2026-01-15T10:30:00.000Z'
                          updated_at: '2026-01-20T14:00:00.000Z'
                          deletable: true
                          viewable: true
                          notifications: []
                        relationships:
                          created_by:
                            id: '12345'
                            type: user
                          folder:
                            id: '42'
                            type: custom_feed_folder
                    meta:
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    post:
      operationId: createWebVisitsCustomFeed
      tags:
        - Web Visits
        - v1
      summary: Create a Custom Feed
      description: Create a new custom feed for the given account.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFeedRequestV1'
            examples:
              regionalCleanIntent:
                summary: Multiple OR conditions joined by AND
                description: Filter companies from Hamburg or Brandenburg with pricing/demo page visits
                value:
                  data:
                    type: custom_feed
                    attributes:
                      name: Hamburg/Brandenburg – Clean Intent Traffic
                      notifications: []
                      advanced_filters:
                        type: group
                        operator: and
                        items:
                          - type: group
                            operator: or
                            negated: false
                            items:
                              - type: group
                                operator: and
                                items:
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: is
                                        field: region
                                        value: Hamburg
                                        display_value: Hamburg
                                      - type: filter
                                        operator: is
                                        field: region
                                        value: Brandenburg
                                        display_value: Brandenburg
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: contains
                                        field: page_url
                                        value: pricing
                                        display_value: pricing
                                      - type: filter
                                        operator: contains
                                        field: page_url
                                        value: demo
                                        display_value: demo
                          - type: group
                            operator: or
                            negated: true
                            items: []
                    relationships:
                      folder: null
              highIntentEngaged:
                summary: Multiple AND conditions joined by OR
                description: Filter accounts with both pricing and demo visits OR extended visit duration
                value:
                  data:
                    type: custom_feed
                    attributes:
                      name: High-Intent Engaged Accounts
                      notifications: []
                      advanced_filters:
                        type: group
                        operator: and
                        items:
                          - type: group
                            operator: or
                            negated: false
                            items:
                              - type: group
                                operator: and
                                items:
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: contains
                                        field: page_url
                                        value: pricing
                                        display_value: pricing
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: contains
                                        field: page_url
                                        value: demo
                                        display_value: demo
                              - type: group
                                operator: and
                                items:
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: at_least
                                        field: visit_length
                                        value: 5 minutes
                                        display_value: 5 minutes
                          - type: group
                            operator: or
                            negated: true
                            items: []
                    relationships:
                      folder: null
              enterpriseHighIntent:
                summary: Simple AND conditions
                description: Filter large German companies (201+ employees) with pricing intent or extended visits
                value:
                  data:
                    type: custom_feed
                    attributes:
                      name: DE Enterprise High-Intent Accounts
                      notifications: []
                      advanced_filters:
                        type: group
                        operator: and
                        items:
                          - type: group
                            operator: or
                            negated: false
                            items:
                              - type: group
                                operator: and
                                items:
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: contains
                                        field: page_url
                                        value: pricing
                                        display_value: pricing
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: is
                                        field: country_code
                                        value: DE
                                        display_value: Germany
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: at_least
                                        field: employee_count
                                        value: 201
                                        display_value: '201'
                              - type: group
                                operator: and
                                items:
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        operator: at_least
                                        field: visit_length
                                        value: 5 minutes
                                        display_value: 5 minutes
                          - type: group
                            operator: or
                            negated: true
                            items: []
                    relationships:
                      folder: null
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/CustomFeedV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                customFeed:
                  summary: A single custom feed
                  value:
                    data:
                      type: custom_feed
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      attributes:
                        name: All companies
                        created_at: '2026-01-15T10:30:00.000Z'
                        updated_at: '2026-01-20T14:00:00.000Z'
                        deletable: true
                        viewable: true
                        notifications: []
                      relationships:
                        created_by:
                          id: '12345'
                          type: user
                        folder:
                          id: '42'
                          type: custom_feed_folder
                    meta:
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unprocessable_entity
                    title: The request could not be processed.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/web-visits/custom-feeds/{custom_feed_id}:
    get:
      operationId: getWebVisitsCustomFeed
      tags:
        - Web Visits
        - v1
      summary: Get Custom Feed Details
      description: Retrieve a single custom feed by its ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: custom_feed_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the custom feed.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - folder
          description: Specify which additional data should be attached to the result.
          example: folder
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/CustomFeedV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                customFeed:
                  summary: A single custom feed
                  value:
                    data:
                      type: custom_feed
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      attributes:
                        name: All companies
                        created_at: '2026-01-15T10:30:00.000Z'
                        updated_at: '2026-01-20T14:00:00.000Z'
                        deletable: true
                        viewable: true
                        notifications: []
                      relationships:
                        created_by:
                          id: '12345'
                          type: user
                        folder:
                          id: '42'
                          type: custom_feed_folder
                    meta:
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    patch:
      operationId: updateWebVisitsCustomFeed
      tags:
        - Web Visits
        - v1
      summary: Update Custom Feed
      description: Update an existing custom feed. All attributes are optional; only provided attributes will be updated.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: custom_feed_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the custom feed.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFeedRequestV1'
            examples:
              updateName:
                summary: Update feed name
                description: Update only the name of an existing feed
                value:
                  data:
                    type: custom_feed
                    attributes:
                      name: Updated Feed Name
              updateFilters:
                summary: Update filters
                description: Update the advanced filters for a feed
                value:
                  data:
                    type: custom_feed
                    attributes:
                      name: Enterprise Companies
                      advanced_filters:
                        type: group
                        operator: and
                        items:
                          - type: group
                            operator: or
                            negated: false
                            items:
                              - type: group
                                operator: and
                                items:
                                  - type: group
                                    operator: or
                                    items:
                                      - type: filter
                                        field: employee_count
                                        operator: at_least
                                        value: 500
                                        display_value: 500+
                          - type: group
                            operator: or
                            negated: true
                            items: []
              moveToFolder:
                summary: Move feed to folder
                description: Assign feed to a different folder
                value:
                  data:
                    type: custom_feed
                    attributes:
                      name: My Custom Feed
                    relationships:
                      folder:
                        id: '194'
                        type: custom_feed_folder
              removeFolder:
                summary: Remove folder assignment
                description: Remove feed from its folder
                value:
                  data:
                    type: custom_feed
                    attributes:
                      name: My Custom Feed
                    relationships:
                      folder: null
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/CustomFeedV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                customFeed:
                  summary: A single custom feed
                  value:
                    data:
                      type: custom_feed
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      attributes:
                        name: All companies
                        created_at: '2026-01-15T10:30:00.000Z'
                        updated_at: '2026-01-20T14:00:00.000Z'
                        deletable: true
                        viewable: true
                        notifications: []
                      relationships:
                        created_by:
                          id: '12345'
                          type: user
                        folder:
                          id: '42'
                          type: custom_feed_folder
                    meta:
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unprocessable_entity
                    title: The request could not be processed.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    delete:
      operationId: deleteWebVisitsCustomFeed
      tags:
        - Web Visits
        - v1
      summary: Delete a Custom Feed
      description: Delete a custom feed by its ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: custom_feed_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the custom feed.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                data: null
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/web-visits/custom-feeds-folders:
    get:
      operationId: getWebVisitsCustomFeedFolders
      tags:
        - Web Visits
        - v1
      summary: Retrieve Custom Feeds Folders
      description: Retrieve all custom feed folders accessible to the current user for the given account.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - custom_feeds
          description: Specify which additional data should be attached to the result.
          example: custom_feeds
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomFeedFolderV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                folders:
                  summary: A list of custom feed folders
                  value:
                    data:
                      - type: custom_feed_folder
                        id: '42'
                        attributes:
                          name: Marketing Feeds
                          preset_folder: false
                          created_at: '2026-01-10T08:00:00.000Z'
                          updated_at: '2026-01-15T12:00:00.000Z'
                        relationships:
                          custom_feeds:
                            - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                              type: custom_feed
                    meta:
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/web-visits/tracker:
    get:
      operationId: getWebVisitsTracker
      tags:
        - Web Visits
        - v1
      summary: Retrieve Web Visits Tracker Script
      description: Retrieve the tracking script for the given account. The response includes the script hash and a ready-to-use HTML snippet to embed on your website to enable visitor tracking.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/WebVisitsTrackerScriptV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                tracker:
                  summary: Tracker script details
                  value:
                    data:
                      type: web_visits_tracker_script
                      id: abc123def456
                      attributes:
                        timezone: Europe/Helsinki
                        script:
                          hash: a1b2c3d4e5f6
                          html: <script>(function(ss,ex){ window.ldfdr=window.ldfdr||function(){(ldfdr._q=ldfdr._q||[]).push([].slice.call(arguments));}; (function(d,s){ fs=d.getElementsByTagName(s)[0]; function ce(src){ var cs=d.createElement(s); cs.src=src; cs.async=1; fs.parentNode.insertBefore(cs,fs); }; ce('https://sc.lfeeder.com/lftracker_v1_'+ss+(ex?'_'+ex:'')+'.js'); })(document,'script'); })('a1b2c3d4e5f6');</script>
                    meta:
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
  /v1/web-visits/companies:
    get:
      operationId: getWebVisitsCompanies
      tags:
        - Web Visits
        - v1
      summary: Retrieve Visitor Companies
      description: Retrieve a paginated list of companies that visited your website within a given date range. Each item includes references to the company and its inferred geographic location.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start of the date range (ISO 8601).
          example: '2026-01-01'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End of the date range (ISO 8601).
          example: '2026-01-31'
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
        - name: custom_feed_id
          in: query
          required: false
          schema:
            type: string
          description: Filter results to companies matching a specific custom feed.
          example: abc123def456
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - company
          description: Specify which additional data should be attached to the result.
          example: company
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyLocationV1'
                  meta:
                    type: object
                    required:
                      - pagination
                      - request_id
                    properties:
                      pagination:
                        type: object
                        required:
                          - page_num
                          - page_count
                          - total_count
                        properties:
                          page_num:
                            type: integer
                            example: 1
                          page_count:
                            type: integer
                            example: 1
                          total_count:
                            type: integer
                            example: 1
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                companies:
                  summary: A list of visitor companies
                  value:
                    data:
                      - type: company_location
                        id: 5b4f313e-46de-11e8-b981-05bebed8e58b
                        relationships:
                          company:
                            id: '129011'
                            type: company
                          location:
                            type: location
                            id: 6xeTMh2VfiAzFd86n7GNJ3
                            attributes:
                              country: Finland
                              country_code: FI
                              region: Uusimaa
                              region_code: FI-18
                              city: Helsinki
                              geonames_id: '658225'
                              state_code: FI-18
                    meta:
                      pagination:
                        page_num: 1
                        page_count: 1
                        total_count: 1
                      request_id: cf054205-dd8c-4473-8689-07c30fe0789f
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: bad_request
                    title: Invalid request body or missing required fields
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: unauthorized
                    title: You need to pass a header named `X-Api-Key` that contains a valid API key.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              examples:
                invalid_api_key:
                  value:
                    errors:
                      - code: invalid_api_key
                        title: The provided API key is invalid.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
                access_denied:
                  value:
                    errors:
                      - code: access_denied
                        title: You do not have permissions to perform this action.
                    meta:
                      request_id: 123e4567-e89b-12d3-a456-426614174000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: entity_not_found
                    title: The company with the ID 'xyz' could not be found.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: too_many_requests
                    title: You've exceeded the maximum amount of allowed requests. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: internal_server_error
                    title: An internal error occurred on the server side. Please try again later.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
        '504':
          description: Server timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorObjectV1'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
              example:
                errors:
                  - code: server_timeout
                    title: The request could not be completed because the server took too long to respond.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  parameters:
    AccountIdOptional:
      name: account_id
      in: query
      required: false
      schema:
        type: string
      description: The Leadfeeder Account ID. When provided, the response returns a single account including credit details. If omitted, it returns a list of all accessible accounts without credit information. The Account ID can be retrieved using the **List Accounts** endpoint.
      example: '123456'
    CompanyId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The company's ID. Note that the older string-based ID format continues to be supported.
      example: '159001425'
    AccountId:
      name: account_id
      in: query
      required: true
      schema:
        type: string
      description: The Leadfeeder Account ID. The Account ID can be retrieved using the **List Accounts** endpoint.
      example: '123456'
    CompanyIds:
      name: ids
      in: query
      required: true
      schema:
        type: string
      description: Comma separated list of company IDs. A maximum of 100 IDs can be passed to this endpoint. Note that the older string-based ID format continues to be supported.
      example: 159001425,129011
    PageCursor:
      name: page[cursor]
      in: query
      required: false
      schema:
        type: string
      description: Cursor for pagination. Use this value to fetch the next page of results.
      example: WyAzNzAwMCwgIjIzNTYyMCJd
    PageSize:
      name: page[size]
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: The number of items per page. Maximum is 100.
      example: 20
    ContactId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The contact's ID. Note that the older string-based ID format continues to be supported.
      example: '3219787601'
    ContactIds:
      name: ids
      in: query
      required: true
      schema:
        type: string
      description: Comma separated list of contact IDs. A maximum of 100 IDs can be passed to this endpoint. Note that the older string-based ID format continues to be supported.
      example: 3219787601,3219787635
    PageNum:
      name: page[num]
      in: query
      required: false
      schema:
        type: integer
      description: Page of results to fetch.
      example: 1
    ScopeRequired:
      name: filter[scope]
      in: query
      required: true
      schema:
        type: string
        enum:
          - company
          - contact
      example: company
      description: Filter by entities that apply to either company or contact.
    ScopeOptional:
      name: filter[scope]
      in: query
      required: false
      schema:
        type: string
        enum:
          - company
          - contact
      example: company
      description: Filter by entities that apply to either company or contact. If omitted, returns both kinds of entities.
    FieldTypeOptional:
      name: filter[type]
      in: query
      required: false
      schema:
        type: string
        enum:
          - text
          - number
          - boolean
          - date
          - contact_collection
          - ai_score
          - ai_text
          - ai_number
          - ai_boolean
      example: text
      description: Filter by field type. If omitted, returns all field types.
    TagId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The tag ID.
      example: 4b7e2c9f
    Ip:
      name: ip
      in: query
      required: true
      schema:
        type: string
      example: 185.70.216.139
      description: A valid IPv4 or IPv6 address, e.g. 185.70.216.139 or 2620:0:862:ed1a::1. The IP parameter in the URL should not be quoted (surrounded by " or '). For IPv6, shortened notation is supported, but literal addresses as a part of URI are not. I.e. 2620:0:862:ed1a::1 will succeed, but [2620:0:862:ed1a::1] will return an error response with HTTP status code 400.
  schemas:
    AccountV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          const: account
          example: account
        id:
          type: string
          example: '36744212'
          description: The account ID.
        attributes:
          type: object
          required:
            - name
            - credits
          properties:
            name:
              type: string
              example: Dealfront Group GmbH
              description: The account name.
            credits:
              type: object
              required:
                - available
                - used
                - remaining
                - next_reset_on
              properties:
                available:
                  type: number
                  example: 10000
                  description: The credits included in the subscription.
                used:
                  type: number
                  example: 520
                  description: How many credits were consumed up to now in the account.
                remaining:
                  type: number
                  example: 9480
                  description: How many credits are remaining in the account.
                next_reset_on:
                  type: string
                  format: date
                  example: '2026-10-01'
                  description: The date when the credits will be reset.
    AccountSummaryV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          const: account_summary
          example: account_summary
        id:
          type: string
          example: '36744212'
          description: The account ID.
        attributes:
          type: object
          required:
            - name
          additionalProperties: false
          properties:
            name:
              type: string
              example: Dealfront Group GmbH
              description: The account name.
    ErrorObjectV1:
      type: object
      required:
        - code
        - title
      properties:
        code:
          type: string
          description: A short error code identifying the type of error.
        title:
          type: string
          description: A human-readable message providing more details about the error.
        detail:
          type: string
          description: Additional information about the error, if available.
    CompanyV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: company
          example: company
        id:
          type: string
          description: The Leadfeeder company ID.
          example: '129011'
        attributes:
          type: object
          required:
            - address
            - alternative_names
            - alternative_urls
            - custom_fields
            - description
            - earnings
            - emails
            - employee_count
            - employee_range
            - founded_year
            - industries
            - keywords
            - legal_form
            - logo_url
            - meta
            - name
            - net_worth
            - orientation
            - phones
            - previous_ids
            - register
            - revenue
            - role
            - social_media_profiles
            - url
            - vat_id
            - web_engagement
          properties:
            address:
              type: object
              properties:
                street_address:
                  type:
                    - string
                    - 'null'
                  description: The company's primary street address.
                  example: Durlacher Allee 73
                street_name:
                  type:
                    - string
                    - 'null'
                  description: The street name part of the company's primary address.
                  example: Durlacher Allee
                street_number:
                  type:
                    - string
                    - 'null'
                  description: The street number part of the company's primary address. This field does not necessarily contain a number, values like 1st, 23-35 or 13A are also common.
                  example: '73'
                postal_code:
                  type:
                    - string
                    - 'null'
                  description: The postal code related to the company's physical location. The format varies by country.
                  example: '76131'
                city:
                  type:
                    - string
                    - 'null'
                  description: The city name.
                  example: Karlsruhe
                country:
                  type:
                    - string
                    - 'null'
                  description: The country name.
                  example: Germany
                country_code:
                  type:
                    - string
                    - 'null'
                  description: This field indicates the country supported for Leadfeeder operations and requires a two letter country code according to ISO 3166 Alpha-2 (see [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
                  example: DE
                region:
                  type:
                    - string
                    - 'null'
                  description: The name of the region in native language."
                  example: Baden-Württemberg
                region_code:
                  type:
                    - string
                    - 'null'
                  description: The code for the region. For European companies the NUTS1-3 schema is used. For companies outside of Europe values that comply with ISO 3166-2 with underscores are returned.
                  example: DE1
                geo:
                  type:
                    - object
                    - 'null'
                  properties:
                    latitude:
                      type:
                        - number
                        - 'null'
                      description: The latitude of the geographical point.
                      example: 49.01
                    longitude:
                      type:
                        - number
                        - 'null'
                      description: The longitude of the geographical point.
                      example: 8.43
            alternative_names:
              type: array
              items:
                type: string
              description: An array of alternate / previous spellings of the company name.
              example:
                - Echobot Media Technologies GmbH
                - Dealfront
            alternative_urls:
              type: array
              items:
                type:
                  - string
                  - 'null'
                description: The URL of the company website.
                example: https://www.leadfeeder.com/welcome
              description: A set of alternative URLs related to the company.
              example:
                - https://echobot.de
                - https://dealfront.com
            custom_fields:
              type: object
              description: A dictionary of custom field values, indexed by their unique field IDs.
              additionalProperties:
                type: object
                description: |
                  A custom field value assigned to a company or contact. The `custom_fields` attribute is a map where each key is the custom field's `id` (its internal API name) and the value is an object describing the field type, its value, and an optional AI-generated reason.
                required:
                  - type
                  - value
                properties:
                  type:
                    type: string
                    description: The data type of the custom field
                    enum:
                      - ai_boolean
                      - ai_number
                      - ai_score
                      - ai_text
                      - boolean
                      - contact_collection
                      - date
                      - number
                      - text
                    example: ai_score
                  value:
                    description: |
                      The value of the custom field. The concrete type depends on the `type` property. For `text`, `ai_text`, and `date` types the value is a string. For `number`, `ai_number`, and `ai_score` types the value is an integer. For `boolean` and `ai_boolean` types the value is a boolean. For `contact_collection` the value is an array of objects with an `id` property.
                    oneOf:
                      - type: string
                        description: Used for `text`, `ai_text`, and `date` types
                        example: Germany
                      - type: integer
                        description: Used for `number`, `ai_number`, and `ai_score` types
                        example: 3
                      - type: boolean
                        description: Used for `boolean` and `ai_boolean` types
                        example: false
                      - type: array
                        description: Used for `contact_collection` type
                        items:
                          type: object
                          required:
                            - id
                          properties:
                            id:
                              type: string
                              description: The contact ID
                              example: '3170656125'
                  reason:
                    type:
                      - string
                      - 'null'
                    description: |
                      An AI-generated explanation for the assigned value. Present only for AI-powered custom field types (`ai_score`, `ai_text`, `ai_number`, `ai_boolean`).
                    example: The company provides API-driven identity management and security solutions. While it operates in a sector relevant to digital footprint and market activity, it does not explicitly analyze growth trajectories, headcount trends, or market momentum as described in the search query.
            description:
              type:
                - string
                - 'null'
              description: A text containing information about the company (native language)
              example: Dealfront is the Go-to-Market Platform giving sales and marketing teams the data, applications, and insights they need to win any European market
            earnings:
              type:
                - object
                - 'null'
              required:
                - currency
                - year
                - value
                - estimated
              properties:
                currency:
                  type:
                    - string
                    - 'null'
                  description: Currency of the financial value.
                  example: EUR
                year:
                  type:
                    - number
                    - 'null'
                  description: Year when the financial values was reported (or estimated).
                  example: 2020
                value:
                  type:
                    - number
                    - 'null'
                  description: The amount of the financial value.
                  example: 9694333
                estimated:
                  type: boolean
                  description: Whether the financial value was actually reported or is just an estimation.
                  example: false
            emails:
              type: array
              items:
                type: object
                required:
                  - address
                properties:
                  address:
                    type: string
                    description: A standard e-mail address.
                    example: info@leadfeeder.com
              description: Email address(es) for the company (eg. info@, service@ or support@).
            employee_count:
              type:
                - integer
                - 'null'
              description: The currently known headcount for this company.
              example: 271
            employee_range:
              type:
                - string
                - 'null'
              enum:
                - 1-10
                - 11-100
                - 101-500
                - 501-1.000
                - 1.001-5.000
                - 5.001-10.000
                - 10.000+
                - null
              description: A range indicator of the approximate headcount for this company.
              example: 101-500
            founded_year:
              type:
                - integer
                - 'null'
              description: A number representing the year when the company was founded.
              example: 2017
            industries:
              type: object
              required:
                - nace
                - wz
                - industry
              description: A list of the company's industries.
              properties:
                nace:
                  type: array
                  items:
                    type: object
                    required:
                      - name
                      - code
                    properties:
                      name:
                        type: string
                        description: The name of the industry.
                        example: Computer programming activities
                      code:
                        type: string
                        description: The unique identifier for the industry.
                        example: 62.01.9
                  description: A list of the company's NACE codes.
                wz:
                  type: array
                  items:
                    type: object
                    required:
                      - name
                      - code
                    properties:
                      name:
                        type: string
                        description: The name of the industry.
                        example: Computer programming activities
                      code:
                        type: string
                        description: The unique identifier for the industry.
                        example: 62.01.9
                  description: A list of the company's WZ codes.
                industry:
                  type: array
                  items:
                    properties:
                      name:
                        type: string
                  description: A list of the company's industries sent back with a 'name' field in your preferred language.
                  example:
                    - name: Software Development
            keywords:
              type: array
              items:
                type: string
              description: An array of keywords about the company and its products that have been extracted from the website. They will be returned in your user's language.
              example:
                - Strategy
                - Technology
                - Software Solutions
                - Marketing
                - B2b
            legal_form:
              type:
                - string
                - 'null'
              description: The company's legal form (i.e. GmbH, SARL or Limited).
              example: Limited
            logo_url:
              type:
                - string
                - 'null'
              format: uri
              description: The URL of the company's logo.
              example: https://app.dealfront.com/logos/200/694ad7b1-lf-logo-2026-04-16.jpg
            meta:
              type: object
              required:
                - has_updated_id
                - do_not_contact
                - num_contacts
              properties:
                has_updated_id:
                  type: boolean
                  description: This field will be true if the ID of that company has changed internally. This can happen for example if two companies are merged together. If you've stored a reference to the company ID in your system you should update it with the most current ID that's sent back in the `id` field.
                  example: false
                do_not_contact:
                  type: boolean
                  description: This field is set to true when the company does not want to be contacted for advertisement.
                  example: false
                num_contacts:
                  type:
                    - integer
                    - 'null'
                  description: The amount of contacts that we can provide for this company.
                  example: 99
            name:
              type: string
              example: Dealfront Group GmbH
              description: The legal name of the company
            net_worth:
              type:
                - object
                - 'null'
              required:
                - currency
                - year
                - value
                - estimated
              properties:
                currency:
                  type:
                    - string
                    - 'null'
                  description: Currency of the financial value.
                  example: EUR
                year:
                  type:
                    - number
                    - 'null'
                  description: Year when the financial values was reported (or estimated).
                  example: 2020
                value:
                  type:
                    - number
                    - 'null'
                  description: The amount of the financial value.
                  example: 9694333
                estimated:
                  type: boolean
                  description: Whether the financial value was actually reported or is just an estimation.
                  example: false
            orientation:
              type: array
              items:
                type: string
                enum:
                  - B2B
                  - B2C
                  - OTHER
              description: The target audience(s) of the company. The value 'B2B' indicates that the company is primarily focused on business customers, while 'B2C' indicates a focus on individual consumers. The value 'OTHER' means it’s a public (likely non-commercial) service or institution.
              example:
                - B2B
            phones:
              type: array
              items:
                type: object
                required:
                  - number
                  - type
                  - blacklisted
                properties:
                  number:
                    type: string
                    description: E.164 representation of a phone number.
                    example: +49 721 50057501
                  type:
                    type: string
                    enum:
                      - landline
                      - mobile
                      - fax
                    description: The type of phone number.
                    example: landline
                  blacklisted:
                    type: boolean
                    description: Whether the company is not allowed to be contacted because it's part of a register like https://www.tpsonline.org.uk/pages/what_is_tps in the UK.
                    example: false
              description: The central phone number(s) of the company.
            previous_ids:
              type: array
              items:
                type: string
                description: The Leadfeeder company ID.
                example: '129011'
              description: A list of former ids that the company was known by in the past. The ID may have changed for example due to a merger with another company. The list is empty if there are no previous IDs.
              example:
                - '185907485'
                - '221290577'
                - '223757669'
                - '223760732'
            register:
              type: object
              required:
                - id
                - location
                - status
              properties:
                id:
                  type:
                    - string
                    - 'null'
                  description: The company's registration number from the commercial register.
                  example: HRB711540
                location:
                  type:
                    - string
                    - 'null'
                  description: The company's register location.
                  example: Mannheim
                status:
                  type:
                    - string
                    - 'null'
                  enum:
                    - active
                    - in_liquidation
                    - out_of_business
                    - non_company
                    - null
                  description: The company's status in the commercial register.
                  example: active
            revenue:
              type:
                - object
                - 'null'
              required:
                - currency
                - year
                - value
                - value_eur
                - estimated
              properties:
                currency:
                  type:
                    - string
                    - 'null'
                  description: Currency of the financial value.
                  example: EUR
                year:
                  type:
                    - number
                    - 'null'
                  description: Year when the financial values was reported (or estimated).
                  example: 2020
                value:
                  type:
                    - number
                    - 'null'
                  description: The amount of the financial value.
                  example: 9694333
                value_eur:
                  type:
                    - number
                    - 'null'
                  description: The amount of the financial value, converted to EUR.
                  example: 9694333
                estimated:
                  type: boolean
                  description: Whether the financial value was actually reported or is just an estimation.
                  example: false
            role:
              type:
                - string
                - 'null'
              enum:
                - single_entity
                - group
                - group_member
                - null
              description: This field indicates the role of the company within its group structure.
              example: group_member
              x-apidog-enum:
                - value: single_entity
                  name: Standalone company
                  description: The company is not part of a group.
                - value: group
                  name: Parent company
                  description: The company is the parent of a group.
                - value: group_member
                  name: Subsidiary company
                  description: The company is a subsidiary within a company group.
            social_media_profiles:
              type: object
              description: List of social media pages.
              example:
                facebook:
                  - url: https://www.facebook.com/getdealfront
                instagram:
                  - url: https://instagram.com/getdealfront
                linkedin:
                  - url: https://www.linkedin.com/company/dealfront
                pinterest: []
                twitter:
                  - url: https://twitter.com/getdealfront
                xing: []
                youtube: []
              properties:
                linkedin:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                instagram:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                facebook:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                twitter:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                youtube:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                pinterest:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                xing:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
            url:
              type:
                - string
                - 'null'
              description: The URL of the company website.
              example: https://www.leadfeeder.com/welcome
            vat_id:
              type:
                - string
                - 'null'
              description: The company's VAT ID (tax ID).
              example: DE276265194
            web_engagement:
              type: object
              description: Web engagement data for a company.
              required:
                - last_visit_date
                - intent_score
                - intent_score_tier
                - intent_score_updated_at
              properties:
                last_visit_date:
                  type:
                    - string
                    - 'null'
                  format: date-time
                  description: The datetime of the last visit to the company's website.
                  example: '2026-03-05T12:41:44Z'
                intent_score:
                  type:
                    - number
                    - 'null'
                  description: A decimal score (0-10) representing the level of buying intent predicted for the company, based on tracked activity over the past 90 days.
                  example: 7.5
                intent_score_tier:
                  type:
                    - string
                    - 'null'
                  description: A categorical representation of the intent score, grouped into predefined tiers (`high`, `medium`, `low`) based on internal scoring thresholds.
                  example: high
                intent_score_updated_at:
                  type:
                    - string
                    - 'null'
                  description: The timestamp indicating when the intent score was last calculated or updated.
                  example: '2026-03-05T12:41:44Z'
        relationships:
          type: object
          required:
            - group_company
          properties:
            group_company:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - id
                    - type
                  description: The group company head. The field may be null if the company is a single entity.
                  properties:
                    id:
                      type: string
                      description: The Leadfeeder company ID.
                      example: '129011'
                    type:
                      type: string
                      const: company
                - $ref: '#/components/schemas/CompanyV1'
                - type: 'null'
              description: The group company head. The field may be null if the company is a single entity.  By default this field only contains the `id` and `type` fields, but you can load all  company attributes by passing the `include=group_company` url parameter.
            tags:
              type: array
              items:
                $ref: '#/components/schemas/TagV1'
              description: Tags assigned to the company. By default this field is not displayed, but you can load it by passing the `include=tags` url parameter.
            lists:
              type: array
              items:
                $ref: '#/components/schemas/ListV1'
              description: Lists that include this company. By default this field is not displayed, but you can load it by passing the `include=lists` url parameter.
            web_visits:
              type: array
              items:
                $ref: '#/components/schemas/WebVisitV1'
              description: Web visits associated with the company.  It returns first 20 visits from last 7 days. By default this field is not displayed, but you can load it by passing the `include=web_visits` url parameter.
            crm_connections:
              type: array
              items:
                $ref: '#/components/schemas/CRMConnectionV1'
              description: CRM connections associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_connections` url parameter.
            crm_suggestions:
              type: array
              items:
                $ref: '#/components/schemas/CRMSuggestionV1'
              description: CRM suggestions associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_suggestions` url parameter.
            crm_group_connections:
              type: array
              items:
                $ref: '#/components/schemas/CRMGroupConnectionV1'
              description: CRM group connections associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_group_connections` url parameter.
            icps:
              type: array
              items:
                $ref: '#/components/schemas/ICPV1'
              description: Ideal Customer Profiles (ICPs) defined in the account that this company matches. By default this field is not displayed, but you can load it by passing the `include=icps` url parameter.
    TagV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: tag
          example: tag
        id:
          type: string
          description: The unique identifier for the tag
          examples:
            - 4b7e2c9f
        attributes:
          type: object
          required:
            - name
            - color
            - created_at
            - updated_at
          properties:
            name:
              type: string
              description: The human-readable name of the tag
              example: Prospects
            color:
              type: integer
              description: List of supported color codes
              enum:
                - 0
                - 1
                - 2
                - 3
                - 4
                - 5
                - 6
                - 7
                - 8
                - 9
              x-apidog-enum:
                - value: 0
                  name: '#1B70F0'
                - value: 1
                  name: '#08A360'
                - value: 2
                  name: '#AE540D'
                - value: 3
                  name: '#D42422'
                - value: 4
                  name: '#5A219B'
                - value: 5
                  name: '#073572'
                - value: 6
                  name: '#00838F'
                - value: 7
                  name: '#D42422'
                - value: 8
                  name: '#B61A5C'
                - value: 9
                  name: '#4C3AED'
            created_at:
              type: string
              format: date-time
              description: Date and time when the tag was created
              example: '2024-12-10T15:57:25Z'
            updated_at:
              type: string
              format: date-time
              description: Date and time when the tag was updated
              example: '2024-11-24T11:50:00Z'
          x-apidog-orders:
            - name
            - color
            - created_at
            - updated_at
        relationships:
          type: object
          required:
            - created_by
          properties:
            created_by:
              type: object
              required:
                - id
                - type
              properties:
                id:
                  type: string
                  description: The Leadfeeder user ID.
                  example: '12345'
                type:
                  type: string
                  default: user
    ListV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: list
          example: list
        id:
          type: string
          description: The unique identifier for the list
          examples:
            - company_123
            - contact_456
        attributes:
          type: object
          required:
            - name
            - scope
            - created_at
          properties:
            name:
              type: string
              description: The human-readable name of the List
              example: US Prospects
            scope:
              type: string
              description: The scope type of the list
              enum:
                - company
                - contact
              example: company
            created_at:
              type: string
              format: date-time
              description: Date and time when the list was created
              example: '2024-12-10T15:57:25Z'
            updated_at:
              type: string
              format: date-time
              description: Date and time when the list was updated
              example: '2024-11-24T11:50:00Z'
        relationships:
          type: object
          required:
            - created_by
          properties:
            created_by:
              type: object
              required:
                - id
                - type
              properties:
                id:
                  type: string
                  description: The Leadfeeder user ID.
                  example: '12345'
                type:
                  type: string
                  default: user
    VisitLocationV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          const: visit_location
          example: visit_location
        id:
          type: string
          description: The unique identifier for the location.
          example: 6xeTMh2VfiAzFd86n7GNJ3
        attributes:
          type: object
          required:
            - country
            - country_code
            - region
            - city
            - geonames_id
            - postal_code
          properties:
            country:
              type: string
              description: The country name.
              example: Finland
            country_code:
              type: string
              description: The ISO 3166-1 alpha-2 country code.
              example: FI
            region:
              type: string
              description: The region or state name.
              example: Uusimaa
            city:
              type: string
              description: The city name.
              example: Helsinki
            geonames_id:
              type:
                - string
                - 'null'
              description: The GeoNames ID.
              example: '658225'
            postal_code:
              type: string
              description: The postal code.
    WebVisitV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: web_visit
          example: web_visit
        id:
          type: string
          description: The unique identifier for the web visit.
          example: 5b4f313e-46de-11e8-b981-05bebed8e58b
        attributes:
          type: object
          required:
            - started_at
            - source
            - medium
            - campaign
            - referring_url
            - keyword
            - landing_page_path
            - page_depth
            - visit_length
            - device_type
            - identifiers
            - visitor
            - engagements
          properties:
            started_at:
              type: string
              format: date-time
              description: Datetime when the visit happened, rounded to minutes.
              example: '2026-01-15T10:30:00.000Z'
            source:
              type: string
              description: Referrer traffic source (e.g. facebook).
              example: google
            medium:
              type:
                - string
                - 'null'
              description: Referrer traffic medium (e.g. cpc).
              example: cpc
            campaign:
              type:
                - string
                - 'null'
              description: Value of the utm_campaign or name of AdWords campaign.
              example: HomePage Split
            referring_url:
              type:
                - string
                - 'null'
              description: Referrer URL.
              example: https://www.google.com/search?q=dealfront
            keyword:
              type:
                - string
                - 'null'
              description: Referrer keyword (search engine search phrase).
              example: website leads
            landing_page_path:
              type: string
              description: Path of the first page the visitor viewed.
              example: /home
            page_depth:
              type: integer
              description: Number of page views the visit contains.
              example: 4
            visit_length:
              type: integer
              description: Duration of the visit in seconds.
              example: 80
            device_type:
              type:
                - string
                - 'null'
              description: Identified device type.
              example: smartphone
            identifiers:
              type: object
              required:
                - lf_client_id
                - ga_client_ids
                - adobe_cookies
              properties:
                lf_client_id:
                  type: string
                  description: Visitor's ID as seen by Dealfront.
                  example: LF1.1.a3f8b2d1e4c90123.1742597607000
                ga_client_ids:
                  type: array
                  items:
                    type: string
                  description: Visitor IDs as seen by Google Analytics.
                  example:
                    - '5829104736.1742616961'
                adobe_cookies:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                  description: Visitor's Adobe cookies (MCMID, MCAAMB, MCAAMLH).
                  example:
                    - MCMID: '681245'
                      MCAAMB: RKh123Vc5
                      MCAAMLH: '6'
            visitor:
              type: object
              required:
                - email
                - first_name
                - last_name
              properties:
                email:
                  type:
                    - string
                    - 'null'
                  description: Email address of the identified visitor.
                  example: john.doe@example.com
                first_name:
                  type:
                    - string
                    - 'null'
                  description: First name of the identified visitor.
                  example: John
                last_name:
                  type:
                    - string
                    - 'null'
                  description: Last name of the identified visitor.
                  example: Doe
            engagements:
              type: array
              description: 'The list of engagement events recorded during the visit. Each item represents one of: page view, form submit, file download, or video view.'
              items:
                oneOf:
                  - title: page-view
                    allOf:
                      - type: object
                        required:
                          - hostname
                          - page
                          - previous_page_path
                          - has_met_goals
                        properties:
                          hostname:
                            type: string
                            description: Hostname of the visited page.
                            example: www.leadfeeder.com
                          page:
                            type: object
                            required:
                              - path
                              - title
                              - url
                            properties:
                              path:
                                type: string
                                description: Path part of the visited page URL.
                                example: /pricing/
                              title:
                                type: string
                                description: Title of the visited page.
                                example: Pricing for all stages of growth
                              url:
                                type: string
                                description: Complete URL of the visited page.
                                example: http://www.leadfeeder.com/pricing/
                          previous_page_path:
                            type: string
                            description: Path of the previous visited page.
                            example: (entrance)
                          has_met_goals:
                            type: boolean
                            description: Whether any conversion goals were met on this page.
                            example: false
                      - type: object
                        required:
                          - event_type
                        properties:
                          event_type:
                            type: string
                            default: page-view
                          time_on_page:
                            type: integer
                            description: Time spent on page in seconds.
                            example: 22
                  - title: form-submit
                    allOf:
                      - type: object
                        required:
                          - hostname
                          - page
                          - previous_page_path
                          - has_met_goals
                        properties:
                          hostname:
                            type: string
                            description: Hostname of the visited page.
                            example: www.leadfeeder.com
                          page:
                            type: object
                            required:
                              - path
                              - title
                              - url
                            properties:
                              path:
                                type: string
                                description: Path part of the visited page URL.
                                example: /pricing/
                              title:
                                type: string
                                description: Title of the visited page.
                                example: Pricing for all stages of growth
                              url:
                                type: string
                                description: Complete URL of the visited page.
                                example: http://www.leadfeeder.com/pricing/
                          previous_page_path:
                            type: string
                            description: Path of the previous visited page.
                            example: (entrance)
                          has_met_goals:
                            type: boolean
                            description: Whether any conversion goals were met on this page.
                            example: false
                      - type: object
                        required:
                          - event_type
                          - form
                        properties:
                          event_type:
                            type: string
                            default: form-submit
                          form:
                            type: object
                            description: Form details.
                            properties:
                              id:
                                type:
                                  - string
                                  - 'null'
                                description: The HTML id attribute of the form.
                                example: contact-form
                              class:
                                type:
                                  - string
                                  - 'null'
                                description: The HTML class attribute of the form.
                                example: lead-form
                              action:
                                type:
                                  - string
                                  - 'null'
                                description: The form action URL.
                                example: /submit
                              inputs:
                                type: array
                                description: Submitted form input values.
                                items:
                                  type: object
                                  properties:
                                    name:
                                      type:
                                        - string
                                        - 'null'
                                      description: The input field name.
                                      example: email
                                    value:
                                      type: string
                                      description: The submitted value.
                                      example: user@example.com
                                    type:
                                      type: string
                                      description: The HTML input type.
                                      example: email
                  - title: file-download
                    allOf:
                      - type: object
                        required:
                          - hostname
                          - page
                          - previous_page_path
                          - has_met_goals
                        properties:
                          hostname:
                            type: string
                            description: Hostname of the visited page.
                            example: www.leadfeeder.com
                          page:
                            type: object
                            required:
                              - path
                              - title
                              - url
                            properties:
                              path:
                                type: string
                                description: Path part of the visited page URL.
                                example: /pricing/
                              title:
                                type: string
                                description: Title of the visited page.
                                example: Pricing for all stages of growth
                              url:
                                type: string
                                description: Complete URL of the visited page.
                                example: http://www.leadfeeder.com/pricing/
                          previous_page_path:
                            type: string
                            description: Path of the previous visited page.
                            example: (entrance)
                          has_met_goals:
                            type: boolean
                            description: Whether any conversion goals were met on this page.
                            example: false
                      - type: object
                        required:
                          - event_type
                          - file
                        properties:
                          event_type:
                            type: string
                            default: file-download
                          file:
                            type: object
                            description: File details.
                            properties:
                              name:
                                type:
                                  - string
                                  - 'null'
                                description: The name of the downloaded file.
                                example: product-brochure.pdf
                  - title: video-view
                    allOf:
                      - type: object
                        required:
                          - hostname
                          - page
                          - previous_page_path
                          - has_met_goals
                        properties:
                          hostname:
                            type: string
                            description: Hostname of the visited page.
                            example: www.leadfeeder.com
                          page:
                            type: object
                            required:
                              - path
                              - title
                              - url
                            properties:
                              path:
                                type: string
                                description: Path part of the visited page URL.
                                example: /pricing/
                              title:
                                type: string
                                description: Title of the visited page.
                                example: Pricing for all stages of growth
                              url:
                                type: string
                                description: Complete URL of the visited page.
                                example: http://www.leadfeeder.com/pricing/
                          previous_page_path:
                            type: string
                            description: Path of the previous visited page.
                            example: (entrance)
                          has_met_goals:
                            type: boolean
                            description: Whether any conversion goals were met on this page.
                            example: false
                      - type: object
                        required:
                          - event_type
                          - video
                        properties:
                          event_type:
                            type: string
                            default: video-view
                          video:
                            type: object
                            description: Video details.
                            properties:
                              url:
                                type: string
                                description: The URL of the video.
                                example: https://www.youtube.com/watch?v=abc123
                              title:
                                type:
                                  - string
                                  - 'null'
                                description: The title of the video.
                                example: Product Demo
        relationships:
          type: object
          required:
            - location
            - company
          properties:
            location:
              $ref: '#/components/schemas/VisitLocationV1'
              description: The location inferred from the visitor's IP address. Always included in the response.
            company:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - id
                    - type
                  properties:
                    id:
                      type: string
                      description: The Leadfeeder company ID.
                      example: '129011'
                    type:
                      type: string
                      const: company
                - $ref: '#/components/schemas/CompanyV1'
              description: The company the contact is associated with. By default this field only contains the `id` and `type` fields, but you can load all company attributes by passing the `include=company` url parameter.
    CRMUserV1:
      type: object
      properties:
        type:
          type: string
          description: The type of the object
          const: crm_user
          example: crm_user
        id:
          type: string
          description: The unique identifier for the crm owner
        attributes:
          type: object
          properties:
            first_name:
              type: string
            name:
              type: string
          x-apidog-orders:
            - name
            - first_name
        relationships:
          type: object
          properties: {}
          x-apidog-orders: []
      x-apidog-orders:
        - type
        - id
        - attributes
        - relationships
      required:
        - type
        - id
        - attributes
        - relationships
    CRMOrganizationV1:
      type: object
      properties:
        type:
          type: string
          description: The type of the object
          const: crm_organization
          example: crm_organization
        id:
          type: string
          description: The unique identifier for the crm organization
        attributes:
          type: object
          properties:
            name:
              type: string
            country:
              type: string
            city:
              type: string
            postal_code:
              type: string
            website:
              type: string
            zip_code:
              type: string
            crm_url:
              type: string
          x-apidog-orders:
            - crm_url
            - name
            - country
            - city
            - postal_code
            - zip_code
            - website
          required:
            - name
            - crm_url
        relationships:
          type: object
          properties:
            crm_owner:
              oneOf:
                - type: object
                  properties:
                    id:
                      type: string
                    type:
                      type:
                        - string
                        - 'null'
                      title: ''
                      examples:
                        - crm_user
                  x-apidog-orders:
                    - id
                    - type
                - $ref: '#/components/schemas/CRMUserV1'
          x-apidog-orders:
            - crm_owner
          required:
            - crm_owner
      x-apidog-orders:
        - type
        - id
        - attributes
        - relationships
      required:
        - type
        - id
        - attributes
        - relationships
    CRMContactV1:
      type: object
      properties:
        type:
          type: string
          description: The type of the object
          const: crm_contact
          example: crm_contact
        id:
          type: string
          description: The unique identifier for the crm contact
        attributes:
          type: object
          properties:
            country:
              type: string
            city:
              type: string
            first_name:
              type: string
            last_name:
              type: string
            email:
              type: string
            job_title:
              type: string
            crm_url:
              type: string
          x-apidog-orders:
            - crm_url
            - first_name
            - last_name
            - email
            - country
            - city
            - job_title
        relationships:
          type: object
          properties:
            crm_owner:
              oneOf:
                - type: object
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                      examples:
                        - crm_user
                  x-apidog-orders:
                    - id
                    - type
                  required:
                    - type
                - $ref: '#/components/schemas/CRMUserV1'
          x-apidog-orders:
            - crm_owner
          required:
            - crm_owner
      x-apidog-orders:
        - type
        - id
        - attributes
        - relationships
      required:
        - type
        - id
        - attributes
        - relationships
    CRMLeadV1:
      type: object
      properties:
        type:
          type: string
          description: The type of the object
          const: crm_lead
          example: crm_lead
        id:
          type: string
          description: The unique identifier for the crm lead
        attributes:
          type: object
          properties:
            country:
              type: string
            city:
              type: string
            first_name:
              type: string
            last_name:
              type: string
            email:
              type: string
            organization_name:
              type: string
            job_title:
              type: string
            crm_url:
              type: string
          x-apidog-orders:
            - crm_url
            - first_name
            - last_name
            - organization_name
            - email
            - country
            - city
            - job_title
        relationships:
          type: object
          properties:
            crm_owner:
              oneOf:
                - type: object
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                      examples:
                        - crm_user
                  x-apidog-orders:
                    - id
                    - type
                - $ref: '#/components/schemas/CRMUserV1'
          x-apidog-orders:
            - crm_owner
          required:
            - crm_owner
      x-apidog-orders:
        - type
        - id
        - attributes
        - relationships
      required:
        - type
        - id
        - attributes
        - relationships
    CRMConnectionV1:
      type: object
      properties:
        type:
          type: string
          description: The type of the object
          const: crm_connection
          example: crm_connection
        id:
          type: string
          description: The unique identifier for the crm connection
        attributes:
          type: object
          properties:
            send_visits:
              type: boolean
            primary:
              type: boolean
          x-apidog-orders:
            - send_visits
            - primary
          required:
            - send_visits
            - primary
        relationships:
          type: object
          properties:
            crm_record:
              oneOf:
                - type:
                    - object
                    - 'null'
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                  x-apidog-orders:
                    - id
                    - type
                  required:
                    - id
                    - type
                - $ref: '#/components/schemas/CRMOrganizationV1'
                - $ref: '#/components/schemas/CRMContactV1'
                - $ref: '#/components/schemas/CRMLeadV1'
          x-apidog-orders:
            - crm_record
          required:
            - crm_record
      x-apidog-orders:
        - type
        - id
        - attributes
        - relationships
      required:
        - type
        - id
        - attributes
        - relationships
    CRMSuggestionV1:
      type: object
      properties:
        type:
          type: string
          description: The type of the object
          const: crm_suggestion
          example: crm_suggestion
        id:
          type: string
          description: The unique identifier for the crm suggestion
        attributes:
          type: object
          properties:
            match_score:
              type: number
          x-apidog-orders:
            - match_score
        relationships:
          type: object
          properties:
            crm_record:
              oneOf:
                - type:
                    - object
                    - 'null'
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                  x-apidog-orders:
                    - id
                    - type
                  required:
                    - id
                    - type
                - $ref: '#/components/schemas/CRMOrganizationV1'
                - $ref: '#/components/schemas/CRMContactV1'
                - $ref: '#/components/schemas/CRMLeadV1'
          x-apidog-orders:
            - crm_record
          required:
            - crm_record
      x-apidog-orders:
        - type
        - id
        - attributes
        - relationships
      required:
        - type
        - id
        - attributes
        - relationships
    CRMGroupConnectionV1:
      type: object
      properties:
        type:
          type: string
          description: The type of the object
          const: crm_group_connection
          example: crm_group_connection
        id:
          type: string
          description: The unique identifier for the crm connection
        attributes:
          type: object
          properties: {}
          x-apidog-orders: []
        relationships:
          type: object
          properties:
            crm_connection:
              oneOf:
                - type: object
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                      examples:
                        - crm_connection
                  x-apidog-orders:
                    - id
                    - type
                  required:
                    - id
                    - type
                - $ref: '#/components/schemas/CRMConnectionV1'
            company:
              oneOf:
                - type: object
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                      examples:
                        - company
                  x-apidog-orders:
                    - id
                    - type
                  required:
                    - id
                    - type
                - $ref: '#/components/schemas/CompanyV1'
          x-apidog-orders:
            - crm_connection
            - company
          required:
            - crm_connection
            - company
      x-apidog-orders:
        - type
        - id
        - attributes
        - relationships
      required:
        - type
        - id
        - attributes
        - relationships
      x-apidog-refs: {}
    ICPV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          default: icp
          example: icp
        id:
          type: string
          description: The unique identifier for the ICP
          example: '6080'
        attributes:
          type: object
          required:
            - name
            - created_at
            - filters
          properties:
            name:
              type: string
              description: The human-readable name of the ICP
              example: US Prospects
            created_at:
              type: string
              format: date-time
              description: Date and time when the ICP was created
              example: '2024-12-10T15:57:25Z'
            filters:
              type: object
              description: Filter criteria that define this ICP, grouped by filter category. Categories with no configured criteria are omitted. The object is empty when the ICP has no filters configured.
              properties:
                employee_count:
                  type: array
                  description: Employee count range filters.
                  items:
                    type: object
                    required:
                      - display_value
                      - negated
                    properties:
                      search_value:
                        type: string
                        description: The internal value used to match this filter (e.g. industry code, country code, employee range identifier).
                        example: US
                      display_value:
                        type: string
                        description: The human-readable label of the filter value.
                        example: United States
                      negated:
                        type: boolean
                        description: When true, the filter excludes (rather than includes) matching results.
                        example: false
                industries:
                  type: array
                  description: Industry filters.
                  items:
                    type: object
                    required:
                      - display_value
                      - negated
                    properties:
                      search_value:
                        type: string
                        description: The internal value used to match this filter (e.g. industry code, country code, employee range identifier).
                        example: US
                      display_value:
                        type: string
                        description: The human-readable label of the filter value.
                        example: United States
                      negated:
                        type: boolean
                        description: When true, the filter excludes (rather than includes) matching results.
                        example: false
                location:
                  type: array
                  description: Location filters.
                  items:
                    type: object
                    required:
                      - display_value
                      - negated
                    properties:
                      search_value:
                        type: string
                        description: The internal value used to match this filter (e.g. industry code, country code, employee range identifier).
                        example: US
                      display_value:
                        type: string
                        description: The human-readable label of the filter value.
                        example: United States
                      negated:
                        type: boolean
                        description: When true, the filter excludes (rather than includes) matching results.
                        example: false
    CompanyFinancialsV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          const: company_financials
          example: company_financials
        id:
          type: string
          example: '129011_2024'
        attributes:
          type: object
          required:
            - year
            - consolidated
            - available_indicators
          properties:
            year:
              type: number
              description: Which year the financial indicators are for.
              example: 2024
            consolidated:
              type: boolean
              description: Indicates if the financial indicators are consolidated.
              example: true
            available_indicators:
              type: array
              description: The available financial indicators for the given year.
              items:
                type: object
                required:
                  - name
                  - type
                  - value
                  - unit
                  - estimated
                properties:
                  name:
                    type: string
                    enum:
                      - accounts_receivable
                      - balance_sheet_total
                      - cash_and_cash_equivalents
                      - creditors_after_one_year
                      - creditors_within_one_year
                      - current_assets
                      - debt
                      - earnings
                      - earnings_cagr
                      - employees
                      - equity
                      - equity_ratio
                      - fixed_assets
                      - issued_share_capital
                      - liabilities
                      - materials_expenditure
                      - net_current_assets
                      - operation_expenses
                      - operation_result
                      - pension_provisions
                      - real_estate_expenditures
                      - return_on_equity
                      - return_on_sales
                      - revenue
                      - revenue_cagr
                      - revenue_per_employee
                      - salaries_paid
                      - salaries_per_employee
                      - tax_paid
                      - tax_ratio
                      - total_assets_less_current_liabilities
                    description: The name of the financial indicator.
                    example: revenue_per_employee
                    x-apidog-enum:
                      - value: accounts_receivable
                        name: Accounts Receivable
                        description: Money owed to the company by its customers for goods or services delivered but not yet paid for.
                      - value: balance_sheet_total
                        name: Balance Sheet Total
                        description: The total value of all assets on the company's balance sheet.
                      - value: cash_and_cash_equivalents
                        name: Cash and Cash Equivalents
                        description: Liquid assets including cash on hand, cash in bank accounts, and short-term investments easily convertible to cash.
                      - value: creditors_after_one_year
                        name: Creditors After One Year
                        description: Long-term debts and obligations that are due for payment more than one year from the balance sheet date.
                      - value: creditors_within_one_year
                        name: Creditors Within One Year
                        description: Short-term debts and obligations that are due for payment within one year from the balance sheet date.
                      - value: current_assets
                        name: Current Assets
                        description: Assets that are expected to be converted to cash or used up within one year, including inventory, accounts receivable, and cash.
                      - value: debt
                        name: Debt
                        description: Total amount of money borrowed by the company that must be repaid, including both short-term and long-term obligations.
                      - value: earnings
                        name: Earnings
                        description: The company's net profit or income after deducting all expenses, taxes, and costs from revenue.
                      - value: earnings_cagr
                        name: Earnings CAGR
                        description: Compound Annual Growth Rate of earnings, showing the mean annual growth rate of earnings over a specified period.
                      - value: employees
                        name: Employees
                        description: Total number of people employed by the company.
                      - value: equity
                        name: Equity
                        description: The residual interest in the assets of the company after deducting liabilities, representing ownership value.
                      - value: equity_ratio
                        name: Equity Ratio
                        description: The proportion of total assets financed by shareholders' equity, indicating financial stability and leverage.
                      - value: fixed_assets
                        name: Fixed Assets
                        description: Long-term tangible assets used in operations, such as property, plant, and equipment.
                      - value: issued_share_capital
                        name: Issued Share Capital
                        description: The total value of shares that have been issued and are owned by shareholders.
                      - value: liabilities
                        name: Liabilities
                        description: Total debts and obligations owed by the company to creditors and other parties.
                      - value: materials_expenditure
                        name: Materials Expenditure
                        description: Costs incurred for raw materials, components, and supplies used in production or operations.
                      - value: net_current_assets
                        name: Net Current Assets
                        description: Current assets minus current liabilities, indicating short-term financial health and liquidity.
                      - value: operation_expenses
                        name: Operation Expenses
                        description: Costs incurred in the normal course of business operations, excluding cost of goods sold.
                      - value: operation_result
                        name: Operation Result
                        description: Profit or loss from core business operations, excluding non-operating income and expenses.
                      - value: pension_provisions
                        name: Pension Provisions
                        description: Funds set aside to meet future pension obligations to employees.
                      - value: real_estate_expenditures
                        name: Real Estate Expenditures
                        description: Costs related to real estate investments, purchases, or improvements.
                      - value: return_on_equity
                        name: Return on Equity
                        description: A measure of financial performance calculated by dividing net income by shareholders' equity.
                      - value: return_on_sales
                        name: Return on Sales
                        description: A profitability ratio calculated by dividing operating profit by net sales revenue.
                      - value: revenue
                        name: Revenue
                        description: Total income generated from the sale of goods or services during a specific period.
                      - value: revenue_cagr
                        name: Revenue CAGR
                        description: Compound Annual Growth Rate of revenue, showing the mean annual growth rate of revenue over a specified period.
                      - value: revenue_per_employee
                        name: Revenue per Employee
                        description: A productivity metric calculated by dividing total revenue by the number of employees.
                      - value: salaries_paid
                        name: Salaries Paid
                        description: Total amount paid to employees as wages and salaries during a specific period.
                      - value: salaries_per_employee
                        name: Salaries per Employee
                        description: Average salary cost per employee, calculated by dividing total salaries by number of employees.
                      - value: tax_paid
                        name: Tax Paid
                        description: Total amount of taxes paid by the company during a specific period.
                      - value: tax_ratio
                        name: Tax Ratio
                        description: The proportion of earnings paid as taxes, indicating the effective tax rate.
                      - value: total_assets_less_current_liabilities
                        name: Total Assets Less Current Liabilities
                        description: A measure of long-term financial stability calculated by subtracting current liabilities from total assets.
                  type:
                    type:
                      - string
                      - number
                    enum:
                      - currency
                      - percentage
                      - number
                    description: The type of the financial indicator.
                    example: currency
                    x-apidog-enum:
                      - value: currency
                        name: Currency
                        description: Indicates that the `value` parameter holds a currency.
                      - value: percentage
                        name: Percentage
                        description: Indicates that the `value` parameter holds a percentage.
                      - value: number
                        name: Number
                        description: Indicates that the `value` parameter is a number.
                  value:
                    type: number
                    description: The value of the financial indicator.
                    example: 1234567
                  unit:
                    type: string
                    description: The unit of the value.
                    example: EUR
                  estimated:
                    type: boolean
                    description: Whether the value is estimated.
                    example: false
    IpAddressExtendedV1:
      type: object
      properties:
        start_ip:
          type: string
          description: The start IP address of the range.
          example: 123.123.124.1
        end_ip:
          type: string
          description: The end IP address of the range. If it is different from the start IP, it resembels an IP range.
          example: 123.123.124.3
        confidence_score:
          type: string
          enum:
            - very_high
            - high
            - medium
            - low
          description: The confidence score of the IP address.
          x-apidog-enum:
            - value: very_high
              name: Very high
              description: Indicates highly reliable data based on recent, consistent traffic observations using multiple sources that strongly link the IP address to the specified company. In addition public IP address records verified by our data quality processes.
            - value: high
              name: High
              description: Indicates reliable identification over a sustained period, with a low margin of error (less than a few percent).
            - value: medium
              name: Medium
              description: Represents IP address connections where the ownership of the IP address has been changing more frequently or where there is a chance of multiple companies sharing the same IP address.
            - value: low
              name: Low
              description: The IP address is unlikely to be associated with the company.
        location:
          type: object
          properties:
            geonames_id:
              type:
                - number
                - 'null'
              description: The geonames ID of the location.
              example: 4379966
            city:
              type:
                - string
                - 'null'
              description: The city of the IP address.
              example: Amsterdam
            region:
              type:
                - string
                - 'null'
              description: The region of the IP address.
              example: Jihocesky Kraj
            country_code:
              type:
                - string
                - 'null'
              description: The country code of the IP address.
              example: CZ
    CompanyIpV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object.
          enum:
            - company_ip
          example: company_ip
        id:
          type: string
          description: The Dealfront company ID.
          example: 4b7e2c9f
        attributes:
          type: object
          required:
            - ips
            - ips_extended
            - has_other_group_companies_with_ips
          properties:
            ips:
              type: array
              items:
                type: string
              description: A list of IP addresses or IP ranges ordered by confidence score (from very high to low). Single IPs are represented as a plain address (e.g. "192.0.2.1"), ranges as "start-end" (e.g. "192.0.2.1-192.0.2.255").
              example:
                - 192.0.2.1
                - 10.0.0.1-10.0.0.255
            ips_extended:
              type: array
              items:
                $ref: '#/components/schemas/IpAddressExtendedV1'
              description: A list of IP addresses or IP ranges in the extended format with additional information such as geo location. The addresses are ordered by confidence score (from very high to low).
            has_other_group_companies_with_ips:
              type: boolean
              description: Whether there are other companies in the same group that also have IP data available.
              example: false
        relationships:
          type: object
          required:
            - company
          properties:
            company:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - id
                    - type
                  properties:
                    id:
                      type: string
                      description: The Leadfeeder company ID.
                      example: '129011'
                    type:
                      type: string
                      const: company
                - $ref: '#/components/schemas/CompanyV1'
              description: The company the IP data belongs to. By default this field only contains the `id` and `type` fields, but you can load all company attributes by passing the `include=company` URL parameter.
    SignalV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: signal
          example: signal
        id:
          type: string
          example: '574654454'
        attributes:
          type: object
          required:
            - category
            - signal_type
            - title
            - content
            - event_date
            - publication_date
          properties:
            category:
              type: string
              enum:
                - business_expansion
                - competitive_landscape
                - event_participation
                - industry_recognition
                - leadership_changes
                - corporate_challenges
                - mergers_and_acquisitions
                - customer_acquisition
                - investment_activity
                - product_and_service_development
                - partnerships_and_collaborations
                - financial_struggles
                - job_ads
                - regulatory_compliance_updates
                - register_updates
              description: Categories to group similar signals together
              example: business_expansion
              x-apidog-enum:
                - value: business_expansion
                  name: Business Expansion
                  description: Events that indicate the company’s physical and operational growth through new office locations, facility upgrades, or increases in headcount, signalling expansion into new markets.
                - value: competitive_landscape
                  name: Competitive Landscape
                  description: Events that reflect the competitive environment in which the company operates, including the identification of new or existing rivals that may influence strategic positioning.
                - value: event_participation
                  name: Event Participation
                  description: Events capturing the company’s active involvement in industry gatherings—such as trade shows, conferences, or exhibitions—to boost brand visibility and create networking opportunities.
                - value: industry_recognition
                  name: Industry Recognition
                  description: Events where the company or its representatives receive formal accolades or awards, underscoring excellence and leadership within their industry.
                - value: leadership_changes
                  name: Leadership Changes
                  description: Events that document shifts in the company’s leadership structure, including new hires, promotions, departures, or retirements of key executives.
                - value: corporate_challenges
                  name: Corporate Challenges
                  description: Events that highlight internal difficulties impacting business performance, including legal disputes, significant workforce reductions, or other operational challenges.
                - value: mergers_and_acquisitions
                  name: Mergers and Acquisitions
                  description: Events involving major corporate restructuring such as mergers, acquisitions, or asset sales that can fundamentally change the company’s strategic direction.
                - value: customer_acquisition
                  name: Customer Acquisition
                  description: Events that demonstrate the company’s success in expanding its client base through signing new clients or securing major contracts.
                - value: investment_activity
                  name: Investment Activity
                  description: Events where the company invests resources in external opportunities—either by investing in other companies or assets, or by securing external financing—to drive growth.
                - value: product_and_service_development
                  name: Product and Service Development
                  description: Events showcasing the company’s commitment to innovation, including the development of new products, enhancements to existing offerings, or integration of new services.
                - value: partnerships_and_collaborations
                  name: Partnerships and Collaborations
                  description: Events where the company forms strategic alliances or partnerships with other organisations to leverage shared resources and expand market reach.
                - value: financial_struggles
                  name: Financial Struggles
                  description: Events that indicate the company is experiencing economic or fiscal challenges, such as declining revenues, increased debt, liquidity issues, or cost-cutting measures.
                - value: job_ads
                  name: Job Ads
                  description: Events that capture the posting of job openings by a company, reflecting hiring initiatives, workforce expansion, or strategic talent acquisition efforts across various departments and roles.
                - value: regulatory_compliance_updates
                  name: Regulatory Compliance Updates
                  description: Events that indicate changes, announcements, or actions related to a company’s adherence to legal, regulatory, or industry standards, including new filings, certifications, audits, or compliance measures that impact operational and strategic practices.
                - value: register_updates
                  name: Register Updates
                  description: Events that reflect changes or additions in official company registries, such as modifications to corporate records, filings with governmental authorities, or updates to ownership and governance information.
            signal_type:
              type: string
              description: Specific type of the signal
              example: expands_facilities
            title:
              type: string
              description: Title of the signal
              example: TS Conductor invests $134M in South Carolina for new manufacturing facility
            content:
              type: string
              description: Extended text content of the signal
              example: B2B sales intelligence platform Dealfront has raised a €30 million investment from AshGrove Capital...
            event_date:
              type: string
              format: date-time
              description: Date and time when the event occurred
              example: '2024-12-10T15:57:25Z'
            publication_date:
              type: string
              format: date-time
              description: Date and time when the signal was published
              example: '2024-11-24T11:50:00Z'
            source_url:
              type: string
              format: uri
              description: URL of the source where the signal was found
              example: https://tech.eu/2024/12/10/dealfront-secures-30m-from-ashgrove-capital-for-b2b-sales-intelligence
            language_code:
              type: string
              description: Language code of the signal content
              example: EN
        relationships:
          type: object
          required:
            - company
          properties:
            company:
              type: object
              additionalProperties: false
              required:
                - id
                - type
              properties:
                id:
                  type: string
                  description: The Leadfeeder company ID.
                  example: '129011'
                type:
                  type: string
                  const: company
    CompanySummaryV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: company_summary
          example: company_summary
        id:
          type: string
          description: The Leadfeeder company ID.
          example: '129011'
        attributes:
          type: object
          required:
            - name
            - role
            - register
            - meta
          properties:
            name:
              type: string
              example: Dealfront Group GmbH
              description: The legal name of the company
            role:
              type:
                - string
                - 'null'
              enum:
                - single_entity
                - group
                - group_member
                - null
              description: This field indicates the role of the company within its group structure.
              example: group_member
              x-apidog-enum:
                - value: single_entity
                  name: Standalone company
                  description: The company is not part of a group.
                - value: group
                  name: Parent company
                  description: The company is the parent of a group.
                - value: group_member
                  name: Subsidiary company
                  description: The company is a subsidiary within a company group.
            register:
              type: object
              properties:
                status:
                  type:
                    - string
                    - 'null'
                  enum:
                    - active
                    - in_liquidation
                    - out_of_business
                    - non_company
                    - null
                  description: The company's status in the commercial register.
                  example: active
            meta:
              type: object
              required:
                - do_not_contact
                - has_updated_id
                - has_phones
                - has_fax
                - has_mail
                - has_contacts
                - has_social_accounts
                - has_register_id
                - has_vat_id
                - has_financials_revenue
                - has_financials_earnings
                - has_financials_net_worth
                - has_ip_addresses
              properties:
                do_not_contact:
                  type: boolean
                  description: This field is set to true when the company does not want to be contacted for advertisement.
                  example: false
                has_updated_id:
                  type: boolean
                  description: This field will be true if the ID of that company has changed internally. This can happen for example if two companies are merged together. If you've stored a reference to the company ID in your system you should update it with the most current ID that's sent back in the `id` field.
                  example: false
                has_phones:
                  type: boolean
                  description: Indicates if you will get back a landline or mobile phone number with the full company object.
                  example: true
                has_fax:
                  type: boolean
                  description: Indicates if you will get back a fax number with the full company object.
                  example: false
                has_mail:
                  type: boolean
                  description: Indicates if you will get back an email address with the full company object.
                  example: true
                has_contacts:
                  type: boolean
                  description: Indicates if contacts are available for the company.
                  example: false
                has_social_accounts:
                  type: boolean
                  description: Indicates if you will get back one or more social accounts with the full company object.
                  example: true
                has_register_id:
                  type: boolean
                  description: Indicates if you will get back a register id with the full company object.
                  example: true
                has_vat_id:
                  type: boolean
                  description: Indicates if you will get back a vat id with the full company object.
                  example: true
                has_financials_revenue:
                  type: boolean
                  description: Indicates if you will get back the revenue with the full company object.
                  example: true
                has_financials_earnings:
                  type: boolean
                  description: Indicates if you will get back the earnings value with the full company object.
                  example: true
                has_financials_net_worth:
                  type: boolean
                  description: Indicates if you will get back the net worth value with the full company object.
                  example: true
                has_ip_addresses:
                  type: boolean
                  description: Indicates if the company has IP data available.
                  example: true
        relationships:
          type: object
          required:
            - group_company
          properties:
            group_company:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - id
                    - type
                  description: The group company head. The field may be null if the company is a single entity.
                  properties:
                    id:
                      type: string
                      description: The Leadfeeder company ID.
                      example: '129011'
                    type:
                      type: string
                      const: company
                - type: 'null'
              description: The group company head. The field may be null if the company is a single entity.
    MaskedCompanySummaryV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: masked_company_summary
          example: masked_company_summary
        id:
          type: string
          description: The Leadfeeder company ID.
          example: '129011'
        attributes:
          type: object
          required:
            - name
            - role
            - register
            - meta
          properties:
            name:
              type: string
              example: Dea*****************
              description: The masked legal name of the company
            role:
              type:
                - string
                - 'null'
              enum:
                - single_entity
                - group
                - group_member
                - null
              description: This field indicates the role of the company within its group structure.
              example: group_member
              x-apidog-enum:
                - value: single_entity
                  name: Standalone company
                  description: The company is not part of a group.
                - value: group
                  name: Parent company
                  description: The company is the parent of a group.
                - value: group_member
                  name: Subsidiary company
                  description: The company is a subsidiary within a company group.
            register:
              type: object
              properties:
                status:
                  type:
                    - string
                    - 'null'
                  enum:
                    - active
                    - in_liquidation
                    - out_of_business
                    - non_company
                    - null
                  description: The company's status in the commercial register.
                  example: active
            meta:
              type: object
              required:
                - do_not_contact
                - has_updated_id
                - has_phones
                - has_fax
                - has_mail
                - has_contacts
                - has_social_accounts
                - has_register_id
                - has_vat_id
                - has_financials_revenue
                - has_financials_earnings
                - has_financials_net_worth
                - has_ip_addresses
              properties:
                do_not_contact:
                  type: boolean
                  description: This field is set to true when the company does not want to be contacted for advertisement.
                  example: false
                has_updated_id:
                  type: boolean
                  description: This field will be true if the ID of that company has changed internally. This can happen for example if two companies are merged together. If you've stored a reference to the company ID in your system you should update it with the most current ID that's sent back in the `id` field.
                  example: false
                has_phones:
                  type: boolean
                  description: Indicates if you will get back a landline or mobile phone number with the full company object.
                  example: true
                has_fax:
                  type: boolean
                  description: Indicates if you will get back a fax number with the full company object.
                  example: false
                has_mail:
                  type: boolean
                  description: Indicates if you will get back an email address with the full company object.
                  example: true
                has_contacts:
                  type: boolean
                  description: Indicates if contacts are available for the company.
                  example: false
                has_social_accounts:
                  type: boolean
                  description: Indicates if you will get back one or more social accounts with the full company object.
                  example: true
                has_register_id:
                  type: boolean
                  description: Indicates if you will get back a register id with the full company object.
                  example: true
                has_vat_id:
                  type: boolean
                  description: Indicates if you will get back a vat id with the full company object.
                  example: true
                has_financials_revenue:
                  type: boolean
                  description: Indicates if you will get back the revenue with the full company object.
                  example: true
                has_financials_earnings:
                  type: boolean
                  description: Indicates if you will get back the earnings value with the full company object.
                  example: true
                has_financials_net_worth:
                  type: boolean
                  description: Indicates if you will get back the net worth value with the full company object.
                  example: true
                has_ip_addresses:
                  type: boolean
                  description: Indicates if the company has IP data available.
                  example: true
        relationships:
          type: object
          required:
            - group_company
          properties:
            group_company:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - id
                    - type
                  description: The group company head. The field may be null if the company is a single entity.
                  properties:
                    id:
                      type: string
                      description: The Leadfeeder company ID.
                      example: '129011'
                    type:
                      type: string
                      const: company
                - type: 'null'
              description: The group company head. The field may be null if the company is a single entity.
    CompanyMatchV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: company_match
          example: company_match
        id:
          type: string
        attributes:
          type: object
          required:
            - match_score
          properties:
            match_score:
              type: number
              format: float
              description: The probability that we have matched the correct company. The field is returned as a float value and ranges between 0 and 1, with 1 being the equivalent of a 100% match probability.
              example: 0.95
        relationships:
          type: object
          required:
            - company_summary
          properties:
            company_summary:
              $ref: '#/components/schemas/CompanySummaryV1'
    BuyerPersonaV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          default: buyer_persona
          example: buyer_persona
          description: The type of the object
        id:
          type: string
          description: The unique identifier for the buyer persona
          example: '7421'
        attributes:
          type: object
          required:
            - name
            - created_at
            - filters
          properties:
            name:
              type: string
              description: The human-readable name of the buyer persona
              example: Sales Managers
            created_at:
              type: string
              format: date-time
              description: Date and time when the buyer persona was created
              example: '2024-12-10T15:57:25Z'
            filters:
              type: object
              description: Filter criteria that define this buyer persona, grouped by filter category. Categories with no configured criteria are omitted. The object is empty when the buyer persona has no filters configured.
              properties:
                department:
                  type: array
                  description: Department filters.
                  items:
                    type: object
                    required:
                      - display_value
                      - negated
                    properties:
                      search_value:
                        type: string
                        description: The internal value used to match this filter (e.g. industry code, country code, employee range identifier).
                        example: US
                      display_value:
                        type: string
                        description: The human-readable label of the filter value.
                        example: United States
                      negated:
                        type: boolean
                        description: When true, the filter excludes (rather than includes) matching results.
                        example: false
                job_title:
                  type: array
                  description: Job title keyword filters.
                  items:
                    type: object
                    required:
                      - display_value
                      - negated
                    properties:
                      search_value:
                        type: string
                        description: The internal value used to match this filter (e.g. industry code, country code, employee range identifier).
                        example: US
                      display_value:
                        type: string
                        description: The human-readable label of the filter value.
                        example: United States
                      negated:
                        type: boolean
                        description: When true, the filter excludes (rather than includes) matching results.
                        example: false
                location:
                  type: array
                  description: Location filters.
                  items:
                    type: object
                    required:
                      - display_value
                      - negated
                    properties:
                      search_value:
                        type: string
                        description: The internal value used to match this filter (e.g. industry code, country code, employee range identifier).
                        example: US
                      display_value:
                        type: string
                        description: The human-readable label of the filter value.
                        example: United States
                      negated:
                        type: boolean
                        description: When true, the filter excludes (rather than includes) matching results.
                        example: false
                seniority:
                  type: array
                  description: Seniority filters.
                  items:
                    type: object
                    required:
                      - display_value
                      - negated
                    properties:
                      search_value:
                        type: string
                        description: The internal value used to match this filter (e.g. industry code, country code, employee range identifier).
                        example: US
                      display_value:
                        type: string
                        description: The human-readable label of the filter value.
                        example: United States
                      negated:
                        type: boolean
                        description: When true, the filter excludes (rather than includes) matching results.
                        example: false
    ContactV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: contact
          example: contact
        id:
          type: string
          description: The Leadfeeder contact ID.
          example: '435834'
        attributes:
          type: object
          required:
            - address
            - affiliation
            - custom_fields
            - departments
            - emails
            - first_name
            - gender
            - hierarchy_level
            - last_name
            - phones
            - position
            - public_sources
            - social_media_profiles
            - title
          properties:
            address:
              type: object
              properties:
                city:
                  type:
                    - string
                    - 'null'
                  description: The city name.
                  example: Karlsruhe
                country_code:
                  type:
                    - string
                    - 'null'
                  description: This field indicates the country supported for Leadfeeder operations and requires a two letter country code according to ISO 3166 Alpha-2 (see [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
                  example: DE
                country:
                  type:
                    - string
                    - 'null'
                  description: The country name.
                  example: Germany
              description: Information about the contact's place of work based on sources like LinkedIn.com.
            affiliation:
              type:
                - string
                - 'null'
              enum:
                - employee
                - group_employee
                - related
              description: Determines how the contact is related to the company.
              example: employee
              x-apidog-enum:
                - value: employee
                  name: Employee
                  description: The contact is an employee of the company.
                - value: group_employee
                  name: Group employee
                  description: The contact works for some organization in the same company group.
                - value: related
                  name: Related
                  description: The contact has some relation to the company.
            custom_fields:
              type: object
              description: A dictionary of custom field values, indexed by their unique field IDs.
              additionalProperties:
                type: object
                description: |
                  A custom field value assigned to a company or contact. The `custom_fields` attribute is a map where each key is the custom field's `id` (its internal API name) and the value is an object describing the field type, its value, and an optional AI-generated reason.
                required:
                  - type
                  - value
                properties:
                  type:
                    type: string
                    description: The data type of the custom field
                    enum:
                      - ai_boolean
                      - ai_number
                      - ai_score
                      - ai_text
                      - boolean
                      - contact_collection
                      - date
                      - number
                      - text
                    example: ai_score
                  value:
                    description: |
                      The value of the custom field. The concrete type depends on the `type` property. For `text`, `ai_text`, and `date` types the value is a string. For `number`, `ai_number`, and `ai_score` types the value is an integer. For `boolean` and `ai_boolean` types the value is a boolean. For `contact_collection` the value is an array of objects with an `id` property.
                    oneOf:
                      - type: string
                        description: Used for `text`, `ai_text`, and `date` types
                        example: Germany
                      - type: integer
                        description: Used for `number`, `ai_number`, and `ai_score` types
                        example: 3
                      - type: boolean
                        description: Used for `boolean` and `ai_boolean` types
                        example: false
                      - type: array
                        description: Used for `contact_collection` type
                        items:
                          type: object
                          required:
                            - id
                          properties:
                            id:
                              type: string
                              description: The contact ID
                              example: '3170656125'
                  reason:
                    type:
                      - string
                      - 'null'
                    description: |
                      An AI-generated explanation for the assigned value. Present only for AI-powered custom field types (`ai_score`, `ai_text`, `ai_number`, `ai_boolean`).
                    example: The company provides API-driven identity management and security solutions. While it operates in a sector relevant to digital footprint and market activity, it does not explicitly analyze growth trajectories, headcount trends, or market momentum as described in the search query.
            departments:
              type: array
              items:
                type: string
                enum:
                  - management_department
                  - unknown_department
                  - sales_department
                  - it_department
                  - business_project_management_department
                  - finance_controlling_department
                  - engineering_department
                  - hr_department
                  - marketing_department
                  - consulting_department
                  - media_communications_department
                  - support_department
                  - rd_department
                  - students_apprentices
                  - production_department
                  - logistics_department
                  - legal_compliance_department
                  - qm_department
                  - product_department
                  - purchasing_department
              description: The departments the contact works in within the company.
              example:
                - marketing_department
                - students_apprentices
              x-apidog-enum:
                - value: management_department
                  name: Management Department
                - value: unknown_department
                  name: Unknown Department
                - value: sales_department
                  name: Sales Department
                - value: it_department
                  name: IT Department
                - value: business_project_management_department
                  name: Business Project Management Department
                - value: finance_controlling_department
                  name: Finance Controlling Department
                - value: engineering_department
                  name: Engineering Department
                - value: hr_department
                  name: HR Department
                - value: marketing_department
                  name: Marketing Department
                - value: consulting_department
                  name: Consulting Department
                - value: media_communications_department
                  name: Media Communications Department
                - value: support_department
                  name: Support Department
                - value: rd_department
                  name: RD Department
                - value: students_apprentices
                  name: Students Apprentices
                - value: production_department
                  name: Production Department
                - value: logistics_department
                  name: Logistics Department
                - value: legal_compliance_department
                  name: Legal Compliance Department
                - value: qm_department
                  name: QM Department
                - value: product_department
                  name: Product Department
                - value: purchasing_department
                  name: Purchasing Department
            emails:
              type: array
              items:
                type: object
                required:
                  - address
                  - source
                properties:
                  address:
                    type: string
                    description: A standard e-mail address.
                    example: info@leadfeeder.com
                  source:
                    type:
                      - string
                      - 'null'
                    description: The identifier of the source of data.
                    example: fullenrich
              description: The contact's e-mail addresses.
            first_name:
              type:
                - string
                - 'null'
              description: The contact's first name.
              example: John
            gender:
              type:
                - string
                - 'null'
              enum:
                - male
                - female
                - other
                - null
              description: The contact's gender.
              example: male
            hierarchy_level:
              type:
                - string
                - 'null'
              enum:
                - employees
                - top_management
                - middle_management
                - unknown_hierarchy
                - null
              description: The hierarchy level the contact has in the company.
              example: employees
            last_name:
              type:
                - string
                - 'null'
              description: The contact's surname.
              example: Doe
            phones:
              type: array
              items:
                type: object
                required:
                  - number
                  - type
                  - blacklisted
                  - source
                properties:
                  number:
                    type: string
                    description: E.164 representation of a phone number.
                    example: +49 721 50057501
                  type:
                    type: string
                    enum:
                      - landline
                      - mobile
                      - fax
                    description: The type of phone number.
                    example: landline
                  blacklisted:
                    type:
                      - boolean
                      - 'null'
                    description: Whether the company is not allowed to be contacted because it's part of a register like https://www.tpsonline.org.uk/pages/what_is_tps in the UK. When null, it means the blacklisted status is unknown.
                    example: false
                  source:
                    type:
                      - string
                      - 'null'
                    description: The identifier of the source of data.
                    example: fullenrich
              description: The contact's direct phone numbers within the company.
            position:
              type:
                - object
                - 'null'
              properties:
                title:
                  type:
                    - string
                    - 'null'
                  description: The contact's job title.
                  example: Geschäftsführer
                language_code:
                  type:
                    - string
                    - 'null'
                  description: A two digit language code indicating the language of the original job title according to ISO 639-1 (see https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes)
                  example: DE
              description: Information about the contact's position within the company.
            public_sources:
              type: array
              items:
                type: object
                description: Detailed sources where information related to the contact was found.
                properties:
                  type:
                    type: string
                    enum:
                      - homepage
                      - web
                      - register
                    description: The type of the source.
                    example: homepage
                  url:
                    type: string
                    description: The URL to the website page for the source.
                    example: https://crowdfunding.dossier.at/unterstuetzerinnen/
            social_media_profiles:
              type: object
              description: List of social media pages.
              example:
                facebook:
                  - url: https://www.facebook.com/getdealfront
                    source: fullenrich
                instagram:
                  - url: https://instagram.com/getdealfront
                    source: null
                linkedin:
                  - url: https://www.linkedin.com/company/dealfront
                    source: fullenrich
                pinterest: []
                twitter:
                  - url: https://twitter.com/getdealfront
                    source: null
                xing: []
                youtube: []
              properties:
                linkedin:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                      source:
                        type:
                          - string
                          - 'null'
                        description: The identifier of the source of data.
                        example: fullenrich
                instagram:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                      source:
                        type:
                          - string
                          - 'null'
                        description: The identifier of the source of data.
                        example: fullenrich
                facebook:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                      source:
                        type:
                          - string
                          - 'null'
                        description: The identifier of the source of data.
                        example: fullenrich
                twitter:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                      source:
                        type:
                          - string
                          - 'null'
                        description: The identifier of the source of data.
                        example: fullenrich
                youtube:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                      source:
                        type:
                          - string
                          - 'null'
                        description: The identifier of the source of data.
                        example: fullenrich
                pinterest:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                      source:
                        type:
                          - string
                          - 'null'
                        description: The identifier of the source of data.
                        example: fullenrich
                xing:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                      source:
                        type:
                          - string
                          - 'null'
                        description: The identifier of the source of data.
                        example: fullenrich
            title:
              type:
                - string
                - 'null'
              description: The contact's title
              example: Dr.
        relationships:
          type: object
          required:
            - company
          properties:
            company:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - id
                    - type
                  properties:
                    id:
                      type: string
                      description: The Leadfeeder company ID.
                      example: '129011'
                    type:
                      type: string
                      const: company
                - $ref: '#/components/schemas/CompanyV1'
              description: The company the contact is associated with. By default this field only contains the `id` and `type` fields, but you can load all company attributes by passing the `include=company` url parameter.
            lists:
              type: array
              items:
                $ref: '#/components/schemas/ListV1'
              description: Lists that include this contact. By default this field is not displayed, but you can load it by passing the `include=lists` url parameter.
            buyer_personas:
              type: array
              items:
                $ref: '#/components/schemas/BuyerPersonaV1'
              description: Buyer personas defined in the account that this contact matches. By default this field is not displayed, but you can load it by passing the `include=buyer_personas` url parameter.
    ContactSummaryV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: contact_summary
          example: contact_summary
        id:
          type: string
          description: The Leadfeeder contact ID.
          example: '435834'
        attributes:
          type: object
          required:
            - full_name
            - gender
            - hierarchy_level
            - meta
          properties:
            full_name:
              type: string
              example: John Doe
            gender:
              type:
                - string
                - 'null'
              enum:
                - male
                - female
                - other
                - null
              description: The contact's gender.
              example: male
            hierarchy_level:
              type:
                - string
                - 'null'
              enum:
                - employees
                - top_management
                - middle_management
                - unknown_hierarchy
                - null
              description: The hierarchy level the contact has in the company.
              example: employees
            meta:
              type: object
              properties:
                has_phones:
                  type: boolean
                  description: Indicates if you will get back a landline or mobile phone number with the full contact object.
                  example: true
                has_mail:
                  type: boolean
                  description: Indicates if you will get back an email address with the full contact object.
                  example: true
                has_social_accounts:
                  type: boolean
                  description: Indicates if you will get back one or more social accounts with the full contact object.
                  example: true
        relationships:
          type: object
          required:
            - company
          properties:
            company:
              type: object
              required:
                - id
                - type
              properties:
                id:
                  type: string
                  description: The Leadfeeder company ID.
                  example: '129011'
                type:
                  type: string
                  const: company_summary
    MaskedContactSummaryV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: masked_contact_summary
          example: masked_contact_summary
        id:
          type: string
          description: The Leadfeeder contact ID.
          example: '435834'
        attributes:
          type: object
          required:
            - full_name
            - gender
            - hierarchy_level
            - meta
          properties:
            full_name:
              type: string
              example: Joh******
            gender:
              type:
                - string
                - 'null'
              enum:
                - male
                - female
                - other
                - null
              description: The contact's gender.
              example: male
            hierarchy_level:
              type:
                - string
                - 'null'
              enum:
                - employees
                - top_management
                - middle_management
                - unknown_hierarchy
                - null
              description: The hierarchy level the contact has in the company.
              example: employees
            meta:
              type: object
              properties:
                has_phones:
                  type: boolean
                  description: Indicates if you will get back a landline or mobile phone number with the full contact object.
                  example: true
                has_mail:
                  type: boolean
                  description: Indicates if you will get back an email address with the full contact object.
                  example: true
                has_social_accounts:
                  type: boolean
                  description: Indicates if you will get back one or more social accounts with the full contact object.
                  example: true
        relationships:
          type: object
          required:
            - company
          properties:
            company:
              type: object
              required:
                - id
                - type
              properties:
                id:
                  type: string
                  description: The Leadfeeder company ID.
                  example: '129011'
                type:
                  type: string
                  const: company_summary
    CustomFieldV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: custom_field
          example: custom_field
        id:
          type: string
          description: The internal name of the custom field. It is based on the initial human-readable name of the field and assigned by the system automatically. It cannot be changed later.
          example: score
        attributes:
          type: object
          required:
            - name
            - scope
            - type
            - read_only
            - source
            - created_at
          properties:
            name:
              type: string
              description: The human-readable name of the custom field
              example: Prospect
            scope:
              type: string
              description: The entity type this custom field applies to
              enum:
                - company
                - contact
              example: company
            type:
              type: string
              description: The data type of the custom field
              enum:
                - text
                - number
                - boolean
                - date
                - contact_collection
                - ai_score
                - ai_text
                - ai_number
                - ai_boolean
              x-apidog-enum:
                - value: text
                  description: A free-form text value
                - value: number
                  description: A numeric value
                - value: boolean
                  description: A true/false value
                - value: date
                  description: A date value
                - value: contact_collection
                  description: A collection of contacts
                - value: ai_score
                  description: An AI-generated score value
                - value: ai_text
                  description: An AI-generated text value
                - value: ai_number
                  description: An AI-generated numeric value
                - value: ai_boolean
                  description: An AI-generated true/false value
              example: text
            read_only:
              type: boolean
            source:
              type: string
              description: The origin of the custom field
              enum:
                - system
                - user
                - crm
                - user/ai_refinement
              x-apidog-enum:
                - value: system
                  description: Created by the system
                - value: user
                  description: Created by a user
                - value: crm
                  description: Imported from a CRM
                - value: user/ai_refinement
                  description: Created by a user via AI refinement
              example: user
            created_at:
              type: string
              format: date-time
              description: Date and time when the custom field was created
              example: '2024-12-10T15:57:25Z'
            updated_at:
              type: string
              format: date-time
              description: Date and time when the custom field was last updated
              example: '2024-11-24T11:50:00Z'
            configuration:
              allOf:
                - description: Configuration for AI and contact_collection field types. Must be a JSON object. Silently ignored for simple field types (`text`, `number`, `boolean`, `date`).
                  oneOf:
                    - title: AI configuration
                      type: object
                      description: Configuration for AI field types. The `prompt` property is required.
                      additionalProperties: false
                      required:
                        - prompt
                      properties:
                        prompt:
                          type: string
                          description: The AI prompt text.
                        prompt_category:
                          type: string
                          description: Optional topical category for the AI prompt. Constrains the prompt to a known group used by xenon to organize prompts across the system.
                          enum:
                            - job_listings
                            - news
                            - funding
                            - growth
                            - technologies
                            - legal_compliance
                            - marketing
                            - leadership_changes
                            - research_and_development
                            - products
                          example: technologies
                        prompt_with_external_data:
                          type: boolean
                          description: Whether the AI prompt should use external data.
                    - title: Contact collection configuration
                      type: object
                      description: Configuration for contact_collection field type. All properties are optional. contacts_to_enrich cannot exceed num_contacts_max_per_company.
                      additionalProperties: false
                      properties:
                        buyer_persona_id:
                          type: string
                          description: Buyer persona identifier used to scope contact discovery (max 50 characters).
                          maxLength: 50
                        num_contacts_max_per_company:
                          type: integer
                          description: Maximum contacts per company
                        find_more_contacts_details:
                          type: boolean
                          description: Enable Company Contacts Reveal (CCR) enrichment
                        contacts_to_enrich:
                          type: integer
                          description: Number of contacts to enrich; required when find_more_contacts_details is true; cannot exceed num_contacts_max_per_company
                          minimum: 1
                        enrich_emails:
                          type: boolean
                          description: Include email enrichment in CCR
                        enrich_phones:
                          type: boolean
                          description: Include phone enrichment in CCR
                - description: Type-specific configuration. Present for AI field types (`ai_score`, `ai_text`, `ai_number`, `ai_boolean`) and `contact_collection`. Absent for simple field types (`text`, `number`, `boolean`, `date`).
        relationships:
          type: object
          required:
            - created_by
          properties:
            created_by:
              type: object
              required:
                - id
                - type
              properties:
                id:
                  type: string
                  description: The Leadfeeder user ID.
                  example: '12345'
                type:
                  type: string
                  default: user
    IpLocationV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          const: ip_location
          example: ip_location
        id:
          type: string
          description: The unique identifier for the location.
          example: '18570216139_658225'
        attributes:
          type: object
          required:
            - city
            - region
            - country_code
            - geonames_id
          properties:
            city:
              type: string
              description: The city name.
              example: Helsinki
            region:
              type: string
              description: The region or state name.
              example: Uusimaa
            country_code:
              type: string
              description: The ISO 3166-1 alpha-2 country code.
              example: FI
            geonames_id:
              type:
                - string
                - 'null'
              description: The GeoNames ID.
              example: '658225'
    NetworkV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: network
          example: network
        id:
          type: string
          example: 180.22.205.1
          description: The network's IP address
        attributes:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: The network name
              example: NTT Docomo Business, Inc.
        relationships:
          type: object
    EnrichedIpV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: enriched_ip
          example: enriched_ip
        id:
          type: string
          example: '18570216139'
        attributes:
          type: object
          required:
            - ip_address
            - company_type
            - confidence_score
            - location
          properties:
            ip_address:
              type: string
              description: The IP address
              example: 185.70.216.139
            company_type:
              type: string
              enum:
                - shared_network
                - company
              description: Indicates whether the IP address is associated with a company or another entity (e.g. an ISP).
              x-apidog-enum:
                - value: shared_network
                  name: Shared-network
                  description: Refers to organizations or entities that often manage public or shared networks. This includes ISPs, universities, malls, hospitals, coworking spaces, and marketing or traffic-generation SaaS platforms.
                - value: company
                  name: Company
                  description: A legal entity listed in the Leadfeeder companies database. These are typically B2B organizations with structured business data.
            confidence_score:
              type: string
              enum:
                - very_high
                - high
                - medium
                - low
              description: The confidence score of the IP address.
              x-apidog-enum:
                - value: very_high
                  name: Very high
                  description: Indicates highly reliable data based on recent, consistent traffic observations using multiple sources that strongly link the IP address to the specified company. In addition public IP address records verified by our data quality processes.
                - value: high
                  name: High
                  description: Indicates reliable identification over a sustained period, with a low margin of error (less than a few percent).
                - value: medium
                  name: Medium
                  description: Represents IP address connections where the ownership of the IP address has been changing more frequently or where there is a chance of multiple companies sharing the same IP address.
                - value: low
                  name: Low
                  description: The IP address is unlikely to be associated with the company.
            location:
              $ref: '#/components/schemas/IpLocationV1'
        relationships:
          type: object
          oneOf:
            - properties:
                company:
                  $ref: '#/components/schemas/CompanyV1'
                  description: The company associated with the IP address.  This field is null if the IP address is not associated with a company.
              required:
                - company
            - properties:
                network:
                  $ref: '#/components/schemas/NetworkV1'
                  description: The network associated with the IP address.
              required:
                - network
    ApiUsageV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          const: api_usage
          example: api_usage
        id:
          type: string
          example: 2025-01_ip/enrich
          description: The unique identifier for the API usage record.
        attributes:
          type: object
          required:
            - period
            - endpoint_path
            - num_requests
            - num_failed_requests
            - num_successful_requests
            - num_returned_entities
          properties:
            period:
              type: string
              pattern: ^\d{4}-\d{2}$
              description: The period for which usage is reported, formatted as YYYY-MM
              example: 2025-01
            endpoint_path:
              type: string
              description: The API endpoint URL
              example: /ip/enrich
            num_requests:
              type: integer
              minimum: 0
              description: Total number of requests returned 200 SUCCESS
              example: 10
            num_failed_requests:
              type: integer
              minimum: 0
              description: Total number of requests resulting in a non-200 SUCCESS response
              example: 2
            num_successful_requests:
              type: integer
              minimum: 0
              description: Number of successful requests — for credit-based endpoints, this counts only when a credit is consumed; for IP endpoints, this counts only when a company match or IP data are returned.
              example: 5
            num_returned_entities:
              type: integer
              minimum: 0
              description: Number of entities returned as part of successful requests.
              example: 100
            last_accessed_at:
              type: string
              format: date-time
              description: The timestamp when this endpoint was last accessed, in ISO8601 format
              example: '2025-01-15T14:30:00Z'
            http_method:
              type: string
              enum:
                - GET
                - POST
                - PUT
                - PATCH
                - DELETE
                - HEAD
                - OPTIONS
              description: |
                The HTTP method used for this endpoint.
              example: POST
    CustomFeedV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: custom_feed
          example: custom_feed
        id:
          type: string
          description: The unique identifier for the custom feed.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        attributes:
          type: object
          required:
            - name
            - created_at
            - updated_at
            - deletable
            - viewable
            - notifications
          properties:
            name:
              type: string
              description: Name of the custom feed.
              example: All companies
            created_at:
              type: string
              format: date-time
              description: Datetime when the custom feed was created.
              example: '2026-01-15T10:30:00.000Z'
            updated_at:
              type: string
              format: date-time
              description: Datetime when the custom feed was last updated.
              example: '2026-01-20T14:00:00.000Z'
            deletable:
              type: boolean
              description: Whether this custom feed can be deleted.
              example: true
            viewable:
              type: boolean
              description: Whether this custom feed can be viewed.
              example: true
            notifications:
              type: array
              description: Notification subscriptions configured for this custom feed.
              items:
                oneOf:
                  - title: User subscription
                    type: object
                    required:
                      - sending_interval
                      - medium
                      - user_id
                    properties:
                      sending_interval:
                        type: string
                        enum:
                          - day
                          - week
                        description: How often the notification is sent.
                        example: day
                      medium:
                        type: string
                        enum:
                          - email
                          - slack
                        description: The delivery channel for the notification.
                        example: email
                      user_id:
                        type: integer
                        description: The Leadfeeder user ID of the subscribed user.
                        example: 12345
                  - title: Email subscription
                    type: object
                    required:
                      - sending_interval
                      - medium
                      - email
                    properties:
                      sending_interval:
                        type: string
                        enum:
                          - day
                          - week
                        description: How often the notification is sent.
                        example: day
                      medium:
                        type: string
                        enum:
                          - email
                          - slack
                        description: The delivery channel for the notification.
                        example: email
                      email:
                        type: string
                        description: Email address of the subscriber.
                        example: subscriber@example.com
            advanced_filters:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - type
                    - operator
                  properties:
                    type:
                      type: string
                      enum:
                        - group
                      description: The filter type
                      example: group
                    operator:
                      type: string
                      enum:
                        - and
                        - or
                      description: The logical operator to apply to items
                      example: and
                    items:
                      type: array
                      description: List of filter groups or conditions
                      items:
                        oneOf:
                          - title: Filter
                            type: object
                            required:
                              - type
                              - field
                              - operator
                              - value
                            properties:
                              type:
                                type: string
                                enum:
                                  - filter
                                description: Indicates this is a filter condition
                                example: filter
                              field:
                                type: string
                                description: |
                                  The field name to which the filter is applied. Available fields include:

                                  **Company/Organization:**
                                  - `organization` - Company/organization ID
                                  - `legal_organization` - Legal organization entity
                                  - `website_address` - Company website URL
                                  - `employee_count` - Number of employees (exact)
                                  - `industry_code` - Industry code

                                  **Location (Company HQ):**
                                  - `country_code` - ISO country code
                                  - `city` - City name
                                  - `region` - State/region
                                  - `continent` - Continent
                                  - `world_region` - World region
                                  - `hq_region`, `hq_country_code`, `hq_continent`, `hq_world_region`, `hq_postal_code` - Headquarters location

                                  **Location (Visit-based):**
                                  - `visit_city`, `visit_region`, `visit_country_code`, `visit_continent`, `visit_world_region` - Visit location data

                                  **Traffic Source:**
                                  - `source_medium` - Combined traffic source and medium
                                  - `referrer` - Referring source
                                  - `referring_url` - Full referring URL
                                  - `medium` - Traffic medium (organic, cpc, referral, etc.)
                                  - `campaign` - Campaign name
                                  - `campaign_type` - Type of campaign
                                  - `keyword` - Search keyword

                                  **Visit Behavior:**
                                  - `device_type` - Device type (desktop, mobile, tablet)
                                  - `visit_length` - Duration of visit
                                  - `visit_pageviews` - Number of page views in visit
                                  - `visits` - Number of visits
                                  - `pageviews` - Page views count
                                  - `quality` - Visit quality score

                                  **Page & Content:**
                                  - `page` - Page path
                                  - `page_url` - Full page URL
                                  - `landing_page_path` - Landing page path
                                  - `hostname` - Website hostname
                                  - `file_download_name` - Downloaded file name
                                  - `form_id` - Form identifier
                                  - `form_submit` - Form submission event
                                  - `video_title`, `video_url` - Video engagement

                                  **CRM Integration:**
                                  - `crm_connection` - Has CRM connection
                                  - `crm_opportunity` - CRM entity IDs
                                  - `crm_lead_owner`, `crm_opportunity_owner`, `crm_organization_owner` - CRM owners
                                  - `crm_lead_created_in_leadfeeder`, `crm_opportunity_created_in_leadfeeder`, `crm_organization_created_in_leadfeeder` - Created in Leadfeeder
                                  - `crm_stage` - CRM pipeline stages
                                  - `crm_opportunity_status` - Opportunity details
                                  - `crm_task_status` - Task status

                                  **People & Contacts:**
                                  - `person_name`, `person_email`, `person_search` - Contact information
                                  - `identified_visitors` - Identified visitor data

                                  **Organization & Management:**
                                  - `followed` - Is being followed
                                  - `assignee` - Assigned user
                                  - `tag` - Tags
                                  - `icp_segment` - ICP segment
                                  - `lead_id` - Lead identifier
                                  - `goal` - Goal tracking

                                  **Marketing Automation:**
                                  - `ems_campaign`, `ems_list` - Email marketing segments
                                  - `event_ems_click_campaign`, `event_ems_click_list` - Email click events
                                  - `companies_list` - Company lists

                                  **Advertising:**
                                  - `ad_content` - Ad content/creative
                                  - `ad_group` - Ad group identifier

                                  **Special Filters:**
                                  - `sent_to_im` - Sent to integration/messaging
                                  - `emailed` - Has been emailed
                                example: country_code
                              operator:
                                type: string
                                enum:
                                  - all_are
                                  - at_least
                                  - begins_with
                                  - contains
                                  - ends_with
                                  - includes
                                  - is
                                  - is_current_user
                                  - is_empty
                                  - is_not
                                  - is_present
                                  - less_than
                                  - none_is
                                  - not_begins_with
                                  - not_contains
                                  - not_includes
                                description: The logical operator applied to the filter
                                example: includes
                              value:
                                oneOf:
                                  - type: string
                                  - type: integer
                                  - type: 'null'
                                description: The value used in the filter condition. Type depends on the field and operator.
                                example: DE
                              display_value:
                                type: string
                                description: Optional display value for UI presentation
                                example: Germany
                          - title: Group
                            type: object
                            required:
                              - type
                              - operator
                              - items
                            properties:
                              type:
                                type: string
                                enum:
                                  - group
                                description: Indicates this is a filter group
                                example: group
                              operator:
                                type: string
                                enum:
                                  - and
                                  - or
                                description: The logical operator to combine items
                                example: or
                              negated:
                                type: boolean
                                description: Whether this filter group is negated
                                example: false
                              items:
                                type: array
                                description: Nested filter conditions or groups
                                items:
                                  type: object
              description: Advanced filters configuration for the custom feed. Returns null if no filters are configured.
        relationships:
          type: object
          required:
            - created_by
          properties:
            created_by:
              oneOf:
                - type: 'null'
                  description: No user associated with this custom feed
                - type: object
                  required:
                    - id
                    - type
                  properties:
                    id:
                      type: string
                      description: The Leadfeeder user ID.
                      example: '12345'
                    type:
                      type: string
                      default: user
              description: The user who originally created the custom feed.
            folder:
              oneOf:
                - type: 'null'
                  description: No folder assigned to this custom feed
                - type: object
                  required:
                    - id
                    - type
                  properties:
                    id:
                      type: string
                      description: The ID of the folder.
                      example: '42'
                    type:
                      type: string
                      example: custom_feed_folder
    CustomFeedRequestV1:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              description: The type of the object
              const: custom_feed
              example: custom_feed
            attributes:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the custom feed
                  example: All companies
                notifications:
                  type: array
                  description: Notification subscriptions for this custom feed
                  items:
                    oneOf:
                      - title: User subscription
                        type: object
                        required:
                          - sending_interval
                          - medium
                          - user_id
                        properties:
                          sending_interval:
                            type: string
                            enum:
                              - day
                              - week
                            description: How often the notification is sent
                            example: day
                          medium:
                            type: string
                            enum:
                              - email
                              - slack
                            description: The delivery channel for the notification
                            example: email
                          user_id:
                            type: integer
                            description: The Leadfeeder user ID of the subscribed user
                            example: 12345
                      - title: Email subscription
                        type: object
                        required:
                          - sending_interval
                          - medium
                          - email
                        properties:
                          sending_interval:
                            type: string
                            enum:
                              - day
                              - week
                            description: How often the notification is sent
                            example: day
                          medium:
                            type: string
                            enum:
                              - email
                              - slack
                            description: The delivery channel for the notification
                            example: email
                          email:
                            type: string
                            description: Email address of the subscriber
                            example: subscriber@example.com
                advanced_filters:
                  type: object
                  description: Advanced filters configuration for the custom feed
                  required:
                    - type
                    - operator
                  properties:
                    type:
                      type: string
                      enum:
                        - group
                      description: The filter type
                      example: group
                    operator:
                      type: string
                      enum:
                        - and
                        - or
                      description: The logical operator to apply to items
                      example: and
                    items:
                      type: array
                      description: List of filter groups or conditions
                      example:
                        - type: group
                          operator: or
                          negated: false
                          items: []
                        - type: group
                          operator: or
                          negated: true
                          items: []
                      items:
                        oneOf:
                          - title: Filter
                            type: object
                            required:
                              - type
                              - field
                              - operator
                              - value
                            properties:
                              type:
                                type: string
                                enum:
                                  - filter
                                description: Indicates this is a filter condition
                                example: filter
                              field:
                                type: string
                                description: |
                                  The field name to which the filter is applied. Available fields include:

                                  **Company/Organization:**
                                  - `organization` - Company/organization ID
                                  - `legal_organization` - Legal organization entity
                                  - `website_address` - Company website URL
                                  - `employee_count` - Number of employees (exact)
                                  - `industry_code` - Industry code

                                  **Location (Company HQ):**
                                  - `country_code` - ISO country code
                                  - `city` - City name
                                  - `region` - State/region
                                  - `continent` - Continent
                                  - `world_region` - World region
                                  - `hq_region`, `hq_country_code`, `hq_continent`, `hq_world_region`, `hq_postal_code` - Headquarters location

                                  **Location (Visit-based):**
                                  - `visit_city`, `visit_region`, `visit_country_code`, `visit_continent`, `visit_world_region` - Visit location data

                                  **Traffic Source:**
                                  - `source_medium` - Combined traffic source and medium
                                  - `referrer` - Referring source
                                  - `referring_url` - Full referring URL
                                  - `medium` - Traffic medium (organic, cpc, referral, etc.)
                                  - `campaign` - Campaign name
                                  - `campaign_type` - Type of campaign
                                  - `keyword` - Search keyword

                                  **Visit Behavior:**
                                  - `device_type` - Device type (desktop, mobile, tablet)
                                  - `visit_length` - Duration of visit
                                  - `visit_pageviews` - Number of page views in visit
                                  - `visits` - Number of visits
                                  - `pageviews` - Page views count
                                  - `quality` - Visit quality score

                                  **Page & Content:**
                                  - `page` - Page path
                                  - `page_url` - Full page URL
                                  - `landing_page_path` - Landing page path
                                  - `hostname` - Website hostname
                                  - `file_download_name` - Downloaded file name
                                  - `form_id` - Form identifier
                                  - `form_submit` - Form submission event
                                  - `video_title`, `video_url` - Video engagement

                                  **CRM Integration:**
                                  - `crm_connection` - Has CRM connection
                                  - `crm_opportunity` - CRM entity IDs
                                  - `crm_lead_owner`, `crm_opportunity_owner`, `crm_organization_owner` - CRM owners
                                  - `crm_lead_created_in_leadfeeder`, `crm_opportunity_created_in_leadfeeder`, `crm_organization_created_in_leadfeeder` - Created in Leadfeeder
                                  - `crm_stage` - CRM pipeline stages
                                  - `crm_opportunity_status` - Opportunity details
                                  - `crm_task_status` - Task status

                                  **People & Contacts:**
                                  - `person_name`, `person_email`, `person_search` - Contact information
                                  - `identified_visitors` - Identified visitor data

                                  **Organization & Management:**
                                  - `followed` - Is being followed
                                  - `assignee` - Assigned user
                                  - `tag` - Tags
                                  - `icp_segment` - ICP segment
                                  - `lead_id` - Lead identifier
                                  - `goal` - Goal tracking

                                  **Marketing Automation:**
                                  - `ems_campaign`, `ems_list` - Email marketing segments
                                  - `event_ems_click_campaign`, `event_ems_click_list` - Email click events
                                  - `companies_list` - Company lists

                                  **Advertising:**
                                  - `ad_content` - Ad content/creative
                                  - `ad_group` - Ad group identifier

                                  **Special Filters:**
                                  - `sent_to_im` - Sent to integration/messaging
                                  - `emailed` - Has been emailed
                                example: country_code
                              operator:
                                type: string
                                enum:
                                  - all_are
                                  - at_least
                                  - begins_with
                                  - contains
                                  - ends_with
                                  - includes
                                  - is
                                  - is_current_user
                                  - is_empty
                                  - is_not
                                  - is_present
                                  - less_than
                                  - none_is
                                  - not_begins_with
                                  - not_contains
                                  - not_includes
                                description: The logical operator applied to the filter
                                example: includes
                              value:
                                oneOf:
                                  - type: string
                                  - type: integer
                                  - type: 'null'
                                description: The value used in the filter condition. Type depends on the field and operator.
                                example: DE
                              display_value:
                                type: string
                                description: Optional display value for UI presentation
                                example: Germany
                          - title: Group
                            type: object
                            required:
                              - type
                              - operator
                              - items
                            properties:
                              type:
                                type: string
                                enum:
                                  - group
                                description: Indicates this is a filter group
                                example: group
                              operator:
                                type: string
                                enum:
                                  - and
                                  - or
                                description: The logical operator to combine items
                                example: or
                              negated:
                                type: boolean
                                description: Whether this filter group is negated
                                example: false
                              items:
                                type: array
                                description: Nested filter conditions or groups
                                items:
                                  type: object
              required:
                - name
            relationships:
              type: object
              properties:
                folder:
                  description: |
                    Folder assignment for the custom feed. Pass `null` (or omit) to
                    leave the feed unfiled, or pass an object referencing a folder ID.
                  default: null
                  oneOf:
                    - type: 'null'
                    - type: object
                      required:
                        - id
                        - type
                      properties:
                        id:
                          type: string
                          description: The ID of the folder
                        type:
                          type: string
                          enum:
                            - custom_feed_folder
                          description: Resource type identifier
          required:
            - type
            - attributes
      required:
        - data
    CustomFeedFolderV1:
      type: object
      required:
        - type
        - id
        - attributes
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: custom_feed_folder
          example: custom_feed_folder
        id:
          type: string
          description: The unique identifier for the custom feed folder.
          example: '42'
        attributes:
          type: object
          required:
            - name
            - preset_folder
            - created_at
            - updated_at
          properties:
            name:
              type: string
              description: The name of the folder.
              example: Marketing Feeds
            preset_folder:
              type:
                - string
                - 'null'
              description: If this is a preset feed folder, the name of the preset folder. Otherwise null.
              example: High-Intent Pages
            created_at:
              type: string
              format: date-time
              description: Datetime when the folder was created.
              example: '2026-01-10T08:00:00.000Z'
            updated_at:
              type: string
              format: date-time
              description: Datetime when the folder was last updated.
              example: '2026-01-15T12:00:00.000Z'
        relationships:
          type: object
          required:
            - custom_feeds
          properties:
            custom_feeds:
              type: array
              description: The custom feeds belonging to this folder.
              items:
                type: object
                required:
                  - id
                  - type
                properties:
                  id:
                    type: string
                    description: The ID of the custom feed.
                    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  type:
                    type: string
                    example: custom_feed
    WebVisitsTrackerScriptV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          const: web_visits_tracker_script
          example: web_visits_tracker_script
        id:
          type: string
          description: The unique identifier for the tracker script.
          example: abc123def456
        attributes:
          type: object
          required:
            - timezone
            - script
          properties:
            timezone:
              type: string
              description: The timezone for the script (e.g., "Europe/Helsinki", "America/New_york").
              example: Europe/Helsinki
            script:
              type: object
              required:
                - hash
                - html
              properties:
                hash:
                  type: string
                  description: The unique script hash used to identify the tracker.
                  example: a1b2c3d4e5f6
                html:
                  type: string
                  description: The HTML code for the tracking script to be inserted in all webpages to be tracked.
                  example: <script>(function(ss,ex){ window.ldfdr=window.ldfdr||function(){(ldfdr._q=ldfdr._q||[]).push([].slice.call(arguments));}; (function(d,s){ fs=d.getElementsByTagName(s)[0]; function ce(src){ var cs=d.createElement(s); cs.src=src; cs.async=1; fs.parentNode.insertBefore(cs,fs); }; ce('https://sc.lfeeder.com/lftracker_v1_'+ss+(ex?'_'+ex:'')+'.js'); })(document,'script'); })('a1b2c3d4e5f6');</script>
    LocationV1:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          description: The type of the object
          const: location
          example: location
        id:
          type: string
          description: The unique identifier for the location.
          example: 6xeTMh2VfiAzFd86n7GNJ3
        attributes:
          type: object
          required:
            - country
            - country_code
            - region
            - region_code
            - city
            - geonames_id
            - state_code
          properties:
            country:
              type: string
              description: The country name.
              example: Finland
            country_code:
              type: string
              description: The ISO 3166-1 alpha-2 country code.
              example: FI
            region:
              type: string
              description: The region or state name.
              example: Uusimaa
            region_code:
              type:
                - string
                - 'null'
              description: The region code.
              example: FI-18
            city:
              type: string
              description: The city name.
              example: Helsinki
            geonames_id:
              type:
                - string
                - 'null'
              description: The GeoNames ID.
              example: '658225'
            state_code:
              type:
                - string
                - 'null'
              description: The state code derived from country and region.
              example: FI-18
    CompanyLocationV1:
      type: object
      required:
        - type
        - id
        - relationships
      properties:
        type:
          type: string
          description: The type of the object
          const: company_location
          example: company_location
        id:
          type: string
          description: The unique identifier for the company location.
          example: 5b4f313e-46de-11e8-b981-05bebed8e58b
        relationships:
          type: object
          required:
            - company
            - location
          properties:
            company:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - id
                    - type
                  properties:
                    id:
                      type: string
                      description: The Leadfeeder company ID.
                      example: '129011'
                    type:
                      type: string
                      const: company
                - $ref: '#/components/schemas/CompanyV1'
              description: The company the contact is associated with. By default this field only contains the `id` and `type` fields, but you can load all company attributes by passing the `include=company` url parameter.
            location:
              $ref: '#/components/schemas/LocationV1'
  responses:
    AccountResponse:
      description: Success
      content:
        application/json:
          schema:
            oneOf:
              - type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
                additionalProperties: false
                title: Single account with credit details
              - type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountSummaryV1'
                  meta:
                    type: object
                    required:
                      - request_id
                    properties:
                      request_id:
                        type: string
                        description: A unique identifier assigned to each API request for end-to-end traceability.
                        example: cf054205-dd8c-4473-8689-07c30fe0789f
                additionalProperties: false
                title: Multiple accounts without credit details
            description: |
              If `account_id` is supplied, the response includes one account with credit details; if omitted, the response is an array of accounts without credit information.
          examples:
            singleAccount:
              summary: Single account with credit details
              value:
                data:
                  - type: account
                    id: '123456'
                    attributes:
                      name: Account 1
                      credits:
                        available: 1000
                        used: 200
                        remaining: 800
                        next_reset_on: '2026-10-01'
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
            multipleAccounts:
              summary: Multiple accounts without credit details
              value:
                data:
                  - type: account_summary
                    id: '123456'
                    attributes:
                      name: Account 1
                  - type: account_summary
                    id: '789012'
                    attributes:
                      name: Account 2
                  - type: account_summary
                    id: '345678'
                    attributes:
                      name: Account 3
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
    Error401:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorObjectV1'
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            errors:
              - code: unauthorized
                title: You need to pass a header named `X-Api-Key` that contains a valid API key.
            meta:
              request_id: 123e4567-e89b-12d3-a456-426614174000
    Error403:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorObjectV1'
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          examples:
            invalid_api_key:
              value:
                errors:
                  - code: invalid_api_key
                    title: The provided API key is invalid.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
            access_denied:
              value:
                errors:
                  - code: access_denied
                    title: You do not have permissions to perform this action.
                meta:
                  request_id: 123e4567-e89b-12d3-a456-426614174000
    Error429:
      description: Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorObjectV1'
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            errors:
              - code: too_many_requests
                title: You've exceeded the maximum amount of allowed requests. Please try again later.
            meta:
              request_id: 123e4567-e89b-12d3-a456-426614174000
    Error500:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorObjectV1'
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            errors:
              - code: internal_server_error
                title: An internal error occurred on the server side. Please try again later.
            meta:
              request_id: 123e4567-e89b-12d3-a456-426614174000
    Error504:
      description: Server timeout
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorObjectV1'
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            errors:
              - code: server_timeout
                title: The request could not be completed because the server took too long to respond.
            meta:
              request_id: 123e4567-e89b-12d3-a456-426614174000
    CompanyResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/CompanyV1'
              meta:
                type: object
                required:
                  - request_id
                  - credits
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    Error404:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorObjectV1'
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            errors:
              - code: entity_not_found
                title: The company with the ID 'xyz' could not be found.
            meta:
              request_id: 123e4567-e89b-12d3-a456-426614174000
    CompaniesResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyV1'
              meta:
                type: object
                required:
                  - request_id
                  - credits
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    CompanyFinancialsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyFinancialsV1'
              meta:
                type: object
                required:
                  - request_id
                  - credits
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    CompanyIpsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyIpV1'
              meta:
                type: object
                required:
                  - request_id
                  - credits
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data:
              - type: company_ip
                id: 4b7e2c9f
                attributes:
                  ips:
                    - 192.0.2.1-192.0.2.255
                    - 192.0.3.1-192.0.3.255
                  ips_extended:
                    - start_ip: 192.0.2.1
                      end_ip: 192.0.2.255
                      confidence_score: very_high
                      location:
                        country_code: DE
                        region: Bavaria
                        city: Munich
                        geonames_id: '2867714'
                    - start_ip: 192.0.3.1
                      end_ip: 192.0.3.255
                      confidence_score: high
                      location:
                        country_code: DE
                        region: Bavaria
                        city: Munich
                        geonames_id: '2867714'
                  has_other_group_companies_with_ips: false
                relationships:
                  company:
                    id: '129011'
                    type: company
            meta:
              credits:
                charged: 1
              request_id: abc-123
    CompaniesSignalsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/SignalV1'
              meta:
                type: object
                required:
                  - credits
                  - pagination
                  - request_id
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 0
                  pagination:
                    type: object
                    required:
                      - total_count
                    properties:
                      next_cursor:
                        type:
                          - string
                          - 'null'
                        example: dXNlcjpVMEc5V0ZYTlo
                      total_count:
                        type: integer
                        example: 1450
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    CompaniesSearchResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                description: Accounts with an active platform subscription receive `CompanySummaryV1` objects, while those without receive `MaskedCompanySummaryV1` objects.
                anyOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/CompanySummaryV1'
                  - type: array
                    items:
                      $ref: '#/components/schemas/MaskedCompanySummaryV1'
              meta:
                type: object
                required:
                  - credits
                  - pagination
                  - request_id
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 0
                  pagination:
                    type: object
                    required:
                      - total_count
                    properties:
                      next_cursor:
                        type:
                          - string
                          - 'null'
                        example: dXNlcjpVMEc5V0ZYTlo
                      total_count:
                        type: integer
                        example: 1450
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    Error400:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorObjectV1'
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            errors:
              - code: bad_request
                title: Invalid request body or missing required fields
            meta:
              request_id: 123e4567-e89b-12d3-a456-426614174000
    ContactResponse:
      description: Returns the contact details for the specified ID. If `include=company` is supplied, the response includes the company details. If no contact is found for the specified ID, a `404` error is raised.
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/ContactV1'
              meta:
                type: object
                required:
                  - request_id
                  - credits
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    ContactsResponse:
      description: Returns the contact details for the specified IDs. If `include=company` is supplied, the responses include the company details. If no contact is found for a certain ID, the `data` field will not contain an entry for that ID.
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/ContactV1'
              meta:
                type: object
                required:
                  - request_id
                  - credits
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    ContactsSearchResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                description: Accounts with an active platform subscription receive `ContactSummaryV1` objects, while those without receive `MaskedContactSummaryV1` objects.
                anyOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/ContactSummaryV1'
                  - type: array
                    items:
                      $ref: '#/components/schemas/MaskedContactSummaryV1'
              meta:
                type: object
                required:
                  - credits
                  - pagination
                  - request_id
                properties:
                  credits:
                    type: object
                    required:
                      - charged
                    properties:
                      charged:
                        type: number
                        description: How many credits were consumed for this request.
                        example: 0
                  pagination:
                    type: object
                    required:
                      - total_count
                    properties:
                      next_cursor:
                        type:
                          - string
                          - 'null'
                        example: dXNlcjpVMEc5V0ZYTlo
                      total_count:
                        type: integer
                        example: 1450
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    ListsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/ListV1'
              meta:
                type: object
                required:
                  - pagination
                  - request_id
                properties:
                  pagination:
                    type: object
                    required:
                      - page_num
                      - page_count
                      - total_count
                    properties:
                      page_num:
                        type: integer
                        example: 1
                      page_count:
                        type: integer
                        example: 1
                      total_count:
                        type: integer
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    ListResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/ListV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    EmptySuccessResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: 'null'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data: null
            meta:
              request_id: cf054205-dd8c-4473-8689-07c30fe0789f
    CustomFieldsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/CustomFieldV1'
              meta:
                type: object
                required:
                  - pagination
                  - request_id
                properties:
                  pagination:
                    type: object
                    required:
                      - page_num
                      - page_count
                      - total_count
                    properties:
                      page_num:
                        type: integer
                        example: 1
                      page_count:
                        type: integer
                        example: 1
                      total_count:
                        type: integer
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    CustomFieldResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/CustomFieldV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    TagsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/TagV1'
              meta:
                type: object
                required:
                  - pagination
                  - request_id
                properties:
                  pagination:
                    type: object
                    required:
                      - page_num
                      - page_count
                      - total_count
                    properties:
                      page_num:
                        type: integer
                        example: 1
                      page_count:
                        type: integer
                        example: 1
                      total_count:
                        type: integer
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data:
              - type: tag
                id: 4b7e2c9f
                attributes:
                  name: Prospects
                  color: 0
                  created_at: '2024-12-10T15:57:25Z'
                  updated_at: '2024-11-24T11:50:00Z'
                relationships:
                  created_by:
                    id: abc123
                    type: user
            meta:
              pagination:
                page_num: 1
                page_count: 1
                total_count: 1
              request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    TagResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/TagV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data:
              type: tag
              id: 4b7e2c9f
              attributes:
                name: Prospects
                color: 0
                created_at: '2024-12-10T15:57:25Z'
                updated_at: '2024-11-24T11:50:00Z'
              relationships:
                created_by:
                  id: abc123
                  type: user
            meta:
              request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    TagDeleteResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: 'null'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data: null
            meta:
              request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    IcpsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/ICPV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data:
              - type: icp
                id: '6080'
                attributes:
                  name: US Tech Companies
                  created_at: '2024-12-10T15:57:25Z'
                  filters:
                    employee_count:
                      - search_value: 101-500
                        display_value: 101-500 employees
                        negated: false
                    industries:
                      - search_value: '1594_6'
                        display_value: Software Development
                        negated: false
                    location:
                      - search_value: US
                        display_value: United States
                        negated: false
              - type: icp
                id: '6081'
                attributes:
                  name: European ICPs
                  created_at: '2024-11-05T10:30:00Z'
                  filters:
                    employee_count:
                      - search_value: 11-50
                        display_value: 11-50 employees
                        negated: false
                    location:
                      - search_value: DE
                        display_value: Germany
                        negated: false
            meta:
              request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    IcpResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/ICPV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data:
              type: icp
              id: '6080'
              attributes:
                name: US Tech Companies
                created_at: '2024-12-10T15:57:25Z'
                filters:
                  employee_count:
                    - search_value: 101-500
                      display_value: 101-500 employees
                      negated: false
                  industries:
                    - search_value: '1594_6'
                      display_value: Software Development
                      negated: false
                  location:
                    - search_value: US
                      display_value: United States
                      negated: false
            meta:
              request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    BuyerPersonasResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/BuyerPersonaV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data:
              - type: buyer_persona
                id: '7421'
                attributes:
                  name: Sales Managers
                  created_at: '2024-12-10T15:57:25Z'
                  filters:
                    department:
                      - search_value: sales
                        display_value: Sales
                        negated: false
                    job_title:
                      - search_value: Manager
                        display_value: Manager
                        negated: false
                    seniority:
                      - search_value: director
                        display_value: Director
                        negated: false
                      - search_value: vp
                        display_value: VP
                        negated: false
                    location:
                      - search_value: US
                        display_value: United States
                        negated: false
              - type: buyer_persona
                id: '7422'
                attributes:
                  name: IT Directors
                  created_at: '2024-11-05T10:30:00Z'
                  filters:
                    department:
                      - search_value: IT
                        display_value: Information Technology
                        negated: false
                    job_title:
                      - search_value: Director
                        display_value: Director
                        negated: false
                    seniority:
                      - search_value: c_level
                        display_value: C Level
                        negated: false
            meta:
              request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    BuyerPersonaResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/BuyerPersonaV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data:
              type: buyer_persona
              id: '7421'
              attributes:
                name: Sales Managers
                created_at: '2024-12-10T15:57:25Z'
                filters:
                  department:
                    - search_value: sales
                      display_value: Sales
                      negated: false
                  job_title:
                    - search_value: Manager
                      display_value: Manager
                      negated: false
                  seniority:
                    - search_value: director
                      display_value: Director
                      negated: false
                    - search_value: vp
                      display_value: VP
                      negated: false
                  location:
                    - search_value: US
                      display_value: United States
                      negated: true
            meta:
              request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    IpEnrichResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/EnrichedIpV1'
              meta:
                type: object
                required:
                  - num_results
                  - request_id
                properties:
                  num_results:
                    type: integer
                    description: Set to 1 if the request is considered successful. Otherwise, it is set to 0.
                    example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
    ApiUsageResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/ApiUsageV1'
              meta:
                type: object
                required:
                  - total_records
                  - request_id
                properties:
                  total_records:
                    type: integer
                    description: The total number of records in the response.
                    example: 100
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            data:
              - type: api_usage
                id: 2025-01_companies/search_POST
                attributes:
                  period: 2025-01
                  endpoint_path: /companies/search
                  http_method: POST
                  num_requests: 10
                  num_failed_requests: 1
                  num_successful_requests: 5
                  num_returned_entities: 100
              - type: api_usage
                id: 2025-03_companies_GET
                attributes:
                  period: 2025-03
                  endpoint_path: /companies
                  http_method: GET
                  num_requests: 25
                  num_failed_requests: 1
                  num_successful_requests: 24
                  num_returned_entities: 48
            meta:
              total_records: 2
              request_id: cf054205-dd8c-4473-8689-07c30fe0789f
    WebVisitsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/WebVisitV1'
              meta:
                type: object
                required:
                  - pagination
                  - request_id
                properties:
                  pagination:
                    type: object
                    required:
                      - page_num
                      - page_count
                      - total_count
                    properties:
                      page_num:
                        type: integer
                        example: 1
                      page_count:
                        type: integer
                        example: 1
                      total_count:
                        type: integer
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          examples:
            webVisits:
              summary: A list of web visits
              value:
                data:
                  - type: web_visit
                    id: 5b4f313e-46de-11e8-b981-05bebed8e58b
                    attributes:
                      started_at: '2026-01-15T10:30:00.000Z'
                      source: google
                      medium: cpc
                      campaign: Homepage Split
                      referring_url: https://www.google.com/search?q=leadfeeder
                      keyword: website leads
                      landing_page_path: /home
                      page_depth: 4
                      visit_length: 80
                      device_type: smartphone
                      identifiers:
                        lf_client_id: LF1.1.a3f8b2d1e4c90123.1742597607000
                        ga_client_ids:
                          - '5829104736.1742616961'
                        adobe_cookies: []
                      visitor:
                        email: null
                        first_name: null
                        last_name: null
                      engagements:
                        - hostname: www.leadfeeder.com
                          page:
                            path: /pricing/
                            title: Pricing for all stages of growth
                            url: http://www.leadfeeder.com/pricing/
                          previous_page_path: (entrance)
                          has_met_goals: false
                          event_type: page-view
                          time_on_page: 22
                    relationships:
                      location:
                        type: location
                        id: 6xeTMh2VfiAzFd86n7GNJ3
                        attributes:
                          country: Finland
                          country_code: FI
                          region: Uusimaa
                          region_code: FI-18
                          city: Helsinki
                          geonames_id: '658225'
                          state_code: FI-18
                      company:
                        id: '129011'
                        type: company
                meta:
                  pagination:
                    page_num: 1
                    page_count: 1
                    total_count: 1
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
    CustomFeedsResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/CustomFeedV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          examples:
            customFeeds:
              summary: A list of custom feeds
              value:
                data:
                  - type: custom_feed
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    attributes:
                      name: All companies
                      created_at: '2026-01-15T10:30:00.000Z'
                      updated_at: '2026-01-20T14:00:00.000Z'
                      deletable: true
                      viewable: true
                      notifications: []
                    relationships:
                      created_by:
                        id: '12345'
                        type: user
                      folder:
                        id: '42'
                        type: custom_feed_folder
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
    CustomFeedResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/CustomFeedV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          examples:
            customFeed:
              summary: A single custom feed
              value:
                data:
                  type: custom_feed
                  id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  attributes:
                    name: All companies
                    created_at: '2026-01-15T10:30:00.000Z'
                    updated_at: '2026-01-20T14:00:00.000Z'
                    deletable: true
                    viewable: true
                    notifications: []
                  relationships:
                    created_by:
                      id: '12345'
                      type: user
                    folder:
                      id: '42'
                      type: custom_feed_folder
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
    Error422:
      description: Unprocessable entity
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorObjectV1'
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          example:
            errors:
              - code: unprocessable_entity
                title: The request could not be processed.
            meta:
              request_id: 123e4567-e89b-12d3-a456-426614174000
    CustomFeedFoldersResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/CustomFeedFolderV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          examples:
            folders:
              summary: A list of custom feed folders
              value:
                data:
                  - type: custom_feed_folder
                    id: '42'
                    attributes:
                      name: Marketing Feeds
                      preset_folder: false
                      created_at: '2026-01-10T08:00:00.000Z'
                      updated_at: '2026-01-15T12:00:00.000Z'
                    relationships:
                      custom_feeds:
                        - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                          type: custom_feed
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
    WebVisitsTrackerResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                $ref: '#/components/schemas/WebVisitsTrackerScriptV1'
              meta:
                type: object
                required:
                  - request_id
                properties:
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          examples:
            tracker:
              summary: Tracker script details
              value:
                data:
                  type: web_visits_tracker_script
                  id: abc123def456
                  attributes:
                    timezone: Europe/Helsinki
                    script:
                      hash: a1b2c3d4e5f6
                      html: <script>(function(ss,ex){ window.ldfdr=window.ldfdr||function(){(ldfdr._q=ldfdr._q||[]).push([].slice.call(arguments));}; (function(d,s){ fs=d.getElementsByTagName(s)[0]; function ce(src){ var cs=d.createElement(s); cs.src=src; cs.async=1; fs.parentNode.insertBefore(cs,fs); }; ce('https://sc.lfeeder.com/lftracker_v1_'+ss+(ex?'_'+ex:'')+'.js'); })(document,'script'); })('a1b2c3d4e5f6');</script>
                meta:
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f
    WebVisitsCompaniesResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyLocationV1'
              meta:
                type: object
                required:
                  - pagination
                  - request_id
                properties:
                  pagination:
                    type: object
                    required:
                      - page_num
                      - page_count
                      - total_count
                    properties:
                      page_num:
                        type: integer
                        example: 1
                      page_count:
                        type: integer
                        example: 1
                      total_count:
                        type: integer
                        example: 1
                  request_id:
                    type: string
                    description: A unique identifier assigned to each API request for end-to-end traceability.
                    example: cf054205-dd8c-4473-8689-07c30fe0789f
          examples:
            companies:
              summary: A list of visitor companies
              value:
                data:
                  - type: company_location
                    id: 5b4f313e-46de-11e8-b981-05bebed8e58b
                    relationships:
                      company:
                        id: '129011'
                        type: company
                      location:
                        type: location
                        id: 6xeTMh2VfiAzFd86n7GNJ3
                        attributes:
                          country: Finland
                          country_code: FI
                          region: Uusimaa
                          region_code: FI-18
                          city: Helsinki
                          geonames_id: '658225'
                          state_code: FI-18
                meta:
                  pagination:
                    page_num: 1
                    page_count: 1
                    total_count: 1
                  request_id: cf054205-dd8c-4473-8689-07c30fe0789f