openapi: 3.0.3
info:
  title: 'SalesKey API Documentation'
  description: 'Programmatically manage your CRM via the SalesKey REST API.'
  version: 1.0.0
servers:
  - url: 'https://{your-subdomain}.saleskey.ai'
tags:
  - name: Leads
    description: "\nProgrammatic access to your CRM Leads. All endpoints require a Bearer API key\nwith the appropriate `leads` permission and a Professional-plan account."
  - name: Deals
    description: "\nProgrammatic access to your CRM Deals. All endpoints require a Bearer API key\nwith the appropriate `deals` permission and a Professional-plan account."
  - name: People
    description: "\nProgrammatic access to your CRM People (contacts). All endpoints require a\nBearer API key with the appropriate `people` permission and a\nProfessional-plan account."
  - name: Organizations
    description: "\nProgrammatic access to your CRM Organizations. All endpoints require a\nBearer API key with the appropriate `organizations` permission and a\nProfessional-plan account."
  - name: Statuses
    description: "\nRead-only access to the Status definitions used by Leads, Deals, People, and\nOrganizations - lets you discover valid `status_id` values before creating\nor updating those resources. Requires a Bearer API key with the `statuses`\npermission and a Professional-plan account. Creating, reordering, and\ndeleting statuses (including reassigning or removing the records on a\nstatus) is a Settings-only capability and is not exposed via the API."
  - name: Labels
    description: "\nRead-only access to the Label definitions used to tag Leads, Deals, and\nProjects. Lets you discover valid label ids to populate the `labels` field\non `POST`/`PATCH /leads` and `/deals` (attaching labels to a record is\nunchanged - still handled there, not by this API). Requires a Bearer API\nkey with the `labels` permission and a Professional-plan account. Creating,\nreordering, and deleting label definitions is a Settings-only capability\nand is not exposed via the API."
  - name: 'Source Channels'
    description: "\nRead-only access to the Source Channel definitions used by Leads and Deals\n(e.g. Website, Referral). Lets you discover valid `source_channel_id`\nvalues before creating or updating those resources. Requires a Bearer API\nkey with the `source_channels` permission and a Professional-plan account.\nCreating, reordering, and deleting source channel definitions is a\nSettings-only capability and is not exposed via the API."
  - name: Pipelines
    description: "\nRead-only access to Deal Pipelines and their stages. Lets you discover\nvalid `pipeline_id`/`pipeline_stage_id` values before creating or updating\na Deal (Leads have no pipeline concept). Requires a Bearer API key with the\n`pipelines` permission and a Professional-plan account. Creating, updating,\nand deleting pipelines/stages - including operations that can reassign or\ndelete every Deal on a pipeline - is a Settings-only capability and is not\nexposed via the API."
  - name: Users
    description: "\nRead-only access to the tenant's Users - lets you discover valid\n`owner_id`, `assignees`, and `followers` values before creating or\nupdating Leads/Deals. Requires a Bearer API key with the `users`\npermission and a Professional-plan account. Inviting, deactivating, and\nmanaging roles for users is a Settings-only capability and is not\nexposed via the API."
  - name: Fields
    description: "\nRead-only access to the fields available on Leads, Deals, People, and\nOrganizations - both built-in and custom - including resolved options for\nselect/multiselect fields. Lets you discover exactly what a create/update\npayload can contain before sending one. Requires a Bearer API key with the\n`fields` permission and a Professional-plan account. Creating, editing, and\nreordering fields is a Settings-only capability and is not exposed via the\nAPI.\n\n`options` is resolved server-side wherever a real backing source exists\n(statuses, labels, source channels, users, people, organizations,\npipelines) for the built-in select fields, and read directly from the\nfield's own stored choices for custom select/multiselect fields. Three\nbuilt-in fields can't be resolved to one flat, context-free list: a Deal's\npipeline stage (valid stages depend on which pipeline is chosen - see\n`GET /pipelines`), and `country`/`currency` (static lists with no backing\ntenant-DB service). For these, `options` is `null` and `options_source` is\nset to `pipeline_stages`, `countries`, or `currencies` instead."
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'Generate an API key under <b>Company Settings → API Keys</b>. The plaintext key is shown only once at creation.'
security:
  -
    default: []
paths:
  /api/v1/leads:
    get:
      summary: 'List leads'
      operationId: listLeads
      description: "Returns a paginated list of leads, filterable by any combination of the\nparams below. Filters accepting an array (`param[]=`) are OR'd together\nwithin the same param and AND'd with every other param. Any param not\nlisted here - including its singular form like `status` or `person` -\nis silently ignored, not applied.\n\nCustom fields (tenant-specific, configured under Settings > Fields) are\nalso filterable by their slug, e.g. `region=Asia` does a partial match;\nappend `_gte`/`_lte` to a numeric or date custom field for range\nfiltering, e.g. `budget_gte=1000`. This suffix behavior only applies to\ncustom fields, not the native params below."
      parameters:
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
            example: 25
        -
          in: query
          name: all
          description: 'When true, returns leads of every status - including archived and converted - and ignores `status_id` if also sent.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'When true, returns leads of every status - including archived and converted - and ignores `status_id` if also sent.'
            example: true
        -
          in: query
          name: status_id
          description: 'Filter by status ID(s) (see GET /statuses).'
          example:
            - 1
            - 2
          required: false
          schema:
            type: array
            description: 'Filter by status ID(s) (see GET /statuses).'
            example:
              - 1
              - 2
            items:
              type: integer
        -
          in: query
          name: archived
          description: 'Include archived leads instead of excluding them (the default).'
          example: false
          required: false
          schema:
            type: boolean
            description: 'Include archived leads instead of excluding them (the default).'
            example: false
        -
          in: query
          name: converted
          description: 'Include converted leads instead of excluding them (the default).'
          example: false
          required: false
          schema:
            type: boolean
            description: 'Include converted leads instead of excluding them (the default).'
            example: false
        -
          in: query
          name: person_id
          description: 'Filter by linked Person ID(s).'
          example:
            - 9
          required: false
          schema:
            type: array
            description: 'Filter by linked Person ID(s).'
            example:
              - 9
            items:
              type: integer
        -
          in: query
          name: organization_id
          description: 'Filter by linked Organization ID(s).'
          example:
            - 4
          required: false
          schema:
            type: array
            description: 'Filter by linked Organization ID(s).'
            example:
              - 4
            items:
              type: integer
        -
          in: query
          name: owner_id
          description: 'Filter by owner user ID(s).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by owner user ID(s).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: assignees
          description: 'Filter by assigned user ID(s).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by assigned user ID(s).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: followers
          description: 'Filter by following user ID(s).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by following user ID(s).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: source_channel_id
          description: 'Filter by Source Channel ID(s) (see GET /source-channels).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by Source Channel ID(s) (see GET /source-channels).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: labels
          description: 'Filter by Label ID(s) (see GET /labels?type=lead).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by Label ID(s) (see GET /labels?type=lead).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: created_by
          description: 'Filter by creator user ID(s).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by creator user ID(s).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: title
          description: 'Partial, case-insensitive match on the lead title.'
          example: Acme
          required: false
          schema:
            type: string
            description: 'Partial, case-insensitive match on the lead title.'
            example: Acme
        -
          in: query
          name: currency
          description: 'Filter by ISO 4217 currency code(s).'
          example:
            - USD
          required: false
          schema:
            type: array
            description: 'Filter by ISO 4217 currency code(s).'
            example:
              - USD
            items:
              type: string
        -
          in: query
          name: value_in_base_currency
          description: "numeric[] `[min]` for a lower bound, or `[min,max]` for a range, on value converted to the account's base currency."
          example: 0
          required: false
          schema:
            type: integer
            description: "numeric[] `[min]` for a lower bound, or `[min,max]` for a range, on value converted to the account's base currency."
            example: 0
        -
          in: query
          name: expected_close_date
          description: '`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).'
          example:
            - '2026-09-01'
          required: false
          schema:
            type: array
            description: '`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).'
            example:
              - '2026-09-01'
            items:
              type: string
        -
          in: query
          name: created_at
          description: '`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).'
          example:
            - '2026-01-01'
            - '2026-08-01'
          required: false
          schema:
            type: array
            description: '`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).'
            example:
              - '2026-01-01'
              - '2026-08-01'
            items:
              type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 42
                      title: 'Acme Corp renewal'
                      value: '5000.00'
                      currency: USD
                      value_in_base_currency: '5000.00'
                      expected_close_date: '2026-09-01'
                      status:
                        id: 1
                        name: New
                        slug: lead-new
                      person:
                        id: 9
                        name: 'John Doe'
                      organization:
                        id: 4
                        name: 'Acme Corp'
                      owner:
                        id: 1
                        name: 'Jane Owner'
                      source_channel: Referral
                      source_channel_id: 1
                      exchange_rate: null
                      labels:
                        -
                          id: 1
                          name: Hot
                      assignees:
                        -
                          id: 1
                          name: 'Jane Owner'
                      followers:
                        -
                          id: 1
                          name: 'Jane Owner'
                      creator:
                        id: 1
                        name: 'Jane Owner'
                      custom_fields:
                        region: Asia
                      created_at: '2026-08-06T12:11:37+00:00'
                      updated_at: '2026-08-11T06:18:26+00:00'
                  links:
                    first: 'https://{your-subdomain}.saleskey.ai/api/v1/leads?per_page=25&page=1'
                    last: 'https://{your-subdomain}.saleskey.ai/api/v1/leads?per_page=25&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    per_page: 25
                    to: 1
                    total: 1
                    path: 'https://{your-subdomain}.saleskey.ai/api/v1/leads'
                    links:
                      -
                        url: null
                        label: '« Previous'
                        page: null
                        active: false
                      -
                        url: 'https://{your-subdomain}.saleskey.ai/api/v1/leads?per_page=25&page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next »'
                        page: null
                        active: false
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 42
                        title: 'Acme Corp renewal'
                        value: '5000.00'
                        currency: USD
                        value_in_base_currency: '5000.00'
                        expected_close_date: '2026-09-01'
                        status:
                          id: 1
                          name: New
                          slug: lead-new
                        person:
                          id: 9
                          name: 'John Doe'
                        organization:
                          id: 4
                          name: 'Acme Corp'
                        owner:
                          id: 1
                          name: 'Jane Owner'
                        source_channel: Referral
                        source_channel_id: 1
                        exchange_rate: null
                        labels:
                          - id: 1
                            name: Hot
                        assignees:
                          - id: 1
                            name: 'Jane Owner'
                        followers:
                          - id: 1
                            name: 'Jane Owner'
                        creator:
                          id: 1
                          name: 'Jane Owner'
                        custom_fields:
                          region: Asia
                        created_at: '2026-08-06T12:11:37+00:00'
                        updated_at: '2026-08-11T06:18:26+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 42
                        title:
                          type: string
                          example: 'Acme Corp renewal'
                        value:
                          type: string
                          example: '5000.00'
                        currency:
                          type: string
                          example: USD
                        value_in_base_currency:
                          type: string
                          example: '5000.00'
                        expected_close_date:
                          type: string
                          example: '2026-09-01'
                        status:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: New
                            slug:
                              type: string
                              example: lead-new
                        person:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 9
                            name:
                              type: string
                              example: 'John Doe'
                        organization:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 4
                            name:
                              type: string
                              example: 'Acme Corp'
                        owner:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                        source_channel:
                          type: string
                          example: Referral
                        source_channel_id:
                          type: integer
                          example: 1
                        exchange_rate:
                          type: string
                          example: null
                          nullable: true
                        labels:
                          type: array
                          example:
                            - id: 1
                              name: Hot
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              name:
                                type: string
                                example: Hot
                        assignees:
                          type: array
                          example:
                            - id: 1
                              name: 'Jane Owner'
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              name:
                                type: string
                                example: 'Jane Owner'
                        followers:
                          type: array
                          example:
                            - id: 1
                              name: 'Jane Owner'
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              name:
                                type: string
                                example: 'Jane Owner'
                        creator:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                        custom_fields:
                          type: object
                          properties:
                            region:
                              type: string
                              example: Asia
                        created_at:
                          type: string
                          example: '2026-08-06T12:11:37+00:00'
                        updated_at:
                          type: string
                          example: '2026-08-11T06:18:26+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/leads?per_page=25&page=1'
                      last:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/leads?per_page=25&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 25
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/leads'
                      links:
                        type: array
                        example:
                          - url: null
                            label: '« Previous'
                            page: null
                            active: false
                          - url: 'https://{your-subdomain}.saleskey.ai/api/v1/leads?per_page=25&page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next »'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '« Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'leads'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'leads'."
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - Leads
    post:
      summary: 'Create a lead'
      operationId: createALead
      description: "`title` is the only required field. Every other field - person,\norganization, owner, status, source, custom fields - is optional and\nwill be left empty or defaulted (owner defaults to the API key's\ncreator, status defaults to the account's default lead status) if\nomitted.\n\n`person` and `organization` are plain names, not IDs. Each is matched\nagainst existing records by an exact, case-insensitive name match - if\nfound, the lead is linked to that existing record; if not found, a new\nrecord is created with just that name (matching the CRM's built-in\n\"select or create\" behavior). Any other field not listed below is\nstored as a custom field."
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 43
                    title: 'Acme Corp renewal'
                    value: '5000.00'
                    currency: USD
                    value_in_base_currency: '5000.00'
                    expected_close_date: '2026-09-01'
                    status:
                      id: 1
                      name: New
                      slug: lead-new
                    person:
                      id: 9
                      name: 'John Doe'
                    organization:
                      id: 4
                      name: 'Acme Corp'
                    owner:
                      id: 1
                      name: 'Jane Owner'
                    source_channel: null
                    source_channel_id: null
                    exchange_rate: null
                    labels: []
                    assignees: []
                    followers: []
                    creator:
                      id: 1
                      name: 'Jane Owner'
                    custom_fields: null
                    created_at: '2026-08-06T12:11:37+00:00'
                    updated_at: '2026-08-06T12:11:37+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 43
                      title:
                        type: string
                        example: 'Acme Corp renewal'
                      value:
                        type: string
                        example: '5000.00'
                      currency:
                        type: string
                        example: USD
                      value_in_base_currency:
                        type: string
                        example: '5000.00'
                      expected_close_date:
                        type: string
                        example: '2026-09-01'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: New
                          slug:
                            type: string
                            example: lead-new
                      person:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: 'John Doe'
                      organization:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 4
                          name:
                            type: string
                            example: 'Acme Corp'
                      owner:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      source_channel:
                        type: string
                        example: null
                        nullable: true
                      source_channel_id:
                        type: string
                        example: null
                        nullable: true
                      exchange_rate:
                        type: string
                        example: null
                        nullable: true
                      labels:
                        type: array
                        example: []
                      assignees:
                        type: array
                        example: []
                      followers:
                        type: array
                        example: []
                      creator:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      custom_fields:
                        type: string
                        example: null
                        nullable: true
                      created_at:
                        type: string
                        example: '2026-08-06T12:11:37+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T12:11:37+00:00'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      title:
                        - 'The title field is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          title:
                            type: array
                            example:
                              - 'The title field is required.'
                            items:
                              type: string
      tags:
        - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: 'The lead title.'
                  example: 'Acme Corp renewal'
                value:
                  type: number
                  description: 'The monetary value of the lead.'
                  example: 5000.0
                currency:
                  type: string
                  description: "ISO 4217 currency code. Defaults to the account's base currency when omitted."
                  example: USD
                exchange_rate:
                  type: number
                  description: "Exchange rate to the account's base currency. Required when `currency` differs from the base currency."
                  example: 1.0
                expected_close_date:
                  type: string
                  description: 'Expected close date (Y-m-d).'
                  example: '2026-09-01'
                person:
                  type: string
                  description: "Person's name - matched to an existing Person by exact name, or created if no match."
                  example: 'John Doe'
                organization:
                  type: string
                  description: "Organization's name - matched to an existing Organization by exact name, or created if no match."
                  example: 'Acme Corp'
                status_id:
                  type: integer
                  description: "Status ID. Defaults to the account's default lead status."
                  example: 1
                source_channel_id:
                  type: integer
                  description: 'Source Channel ID (see GET /source-channels).'
                  example: 1
                source_channel:
                  type: string
                  description: 'Free-text source channel, independent of source_channel_id.'
                  example: Referral
                owner_id:
                  type: integer
                  description: "User ID the lead is assigned to. Defaults to the API key's creator."
                  example: 1
                labels:
                  type: array
                  description: 'Label IDs to attach (see GET /labels?type=lead).'
                  example:
                    - 1
                    - 2
                  items:
                    type: integer
                assignees:
                  type: array
                  description: 'User IDs assigned to the lead.'
                  example:
                    - 1
                  items:
                    type: integer
                followers:
                  type: array
                  description: 'User IDs following the lead.'
                  example:
                    - 1
                  items:
                    type: integer
              required:
                - title
  '/api/v1/leads/{id}':
    get:
      summary: 'Retrieve a lead'
      operationId: retrieveALead
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 42
                    title: 'Acme Corp renewal'
                    value: '5000.00'
                    currency: USD
                    value_in_base_currency: '5000.00'
                    expected_close_date: '2026-09-01'
                    status:
                      id: 1
                      name: New
                      slug: lead-new
                    person:
                      id: 9
                      name: 'John Doe'
                    organization:
                      id: 4
                      name: 'Acme Corp'
                    owner:
                      id: 1
                      name: 'Jane Owner'
                    source_channel: Referral
                    source_channel_id: 1
                    exchange_rate: null
                    labels:
                      -
                        id: 1
                        name: Hot
                    assignees:
                      -
                        id: 1
                        name: 'Jane Owner'
                    followers:
                      -
                        id: 1
                        name: 'Jane Owner'
                    creator:
                      id: 1
                      name: 'Jane Owner'
                    custom_fields:
                      region: Asia
                    created_at: '2026-08-06T12:11:37+00:00'
                    updated_at: '2026-08-11T06:18:26+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 42
                      title:
                        type: string
                        example: 'Acme Corp renewal'
                      value:
                        type: string
                        example: '5000.00'
                      currency:
                        type: string
                        example: USD
                      value_in_base_currency:
                        type: string
                        example: '5000.00'
                      expected_close_date:
                        type: string
                        example: '2026-09-01'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: New
                          slug:
                            type: string
                            example: lead-new
                      person:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: 'John Doe'
                      organization:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 4
                          name:
                            type: string
                            example: 'Acme Corp'
                      owner:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      source_channel:
                        type: string
                        example: Referral
                      source_channel_id:
                        type: integer
                        example: 1
                      exchange_rate:
                        type: string
                        example: null
                        nullable: true
                      labels:
                        type: array
                        example:
                          - id: 1
                            name: Hot
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Hot
                      assignees:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      followers:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      creator:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      custom_fields:
                        type: object
                        properties:
                          region:
                            type: string
                            example: Asia
                      created_at:
                        type: string
                        example: '2026-08-06T12:11:37+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-11T06:18:26+00:00'
        404:
          description: 'Lead not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Lead not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Lead not found.'
      tags:
        - Leads
    patch:
      summary: 'Update a lead'
      operationId: updateALead
      description: "Partial update - send only the fields you want to change.\n\n`person` and `organization` follow the same match-or-create rule as\ncreate: exact, case-insensitive name match against an existing record,\nor a new record is created if no match exists."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 42
                    title: 'Acme Corp renewal (updated)'
                    value: '7500.00'
                    currency: USD
                    value_in_base_currency: '7500.00'
                    expected_close_date: '2026-09-01'
                    status:
                      id: 1
                      name: New
                      slug: lead-new
                    person:
                      id: 9
                      name: 'John Doe'
                    organization:
                      id: 4
                      name: 'Acme Corp'
                    owner:
                      id: 1
                      name: 'Jane Owner'
                    source_channel: Referral
                    source_channel_id: 1
                    exchange_rate: null
                    labels:
                      -
                        id: 1
                        name: Hot
                    assignees:
                      -
                        id: 1
                        name: 'Jane Owner'
                    followers:
                      -
                        id: 1
                        name: 'Jane Owner'
                    creator:
                      id: 1
                      name: 'Jane Owner'
                    custom_fields:
                      region: Asia
                    created_at: '2026-08-06T12:11:37+00:00'
                    updated_at: '2026-08-11T06:18:26+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 42
                      title:
                        type: string
                        example: 'Acme Corp renewal (updated)'
                      value:
                        type: string
                        example: '7500.00'
                      currency:
                        type: string
                        example: USD
                      value_in_base_currency:
                        type: string
                        example: '7500.00'
                      expected_close_date:
                        type: string
                        example: '2026-09-01'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: New
                          slug:
                            type: string
                            example: lead-new
                      person:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: 'John Doe'
                      organization:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 4
                          name:
                            type: string
                            example: 'Acme Corp'
                      owner:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      source_channel:
                        type: string
                        example: Referral
                      source_channel_id:
                        type: integer
                        example: 1
                      exchange_rate:
                        type: string
                        example: null
                        nullable: true
                      labels:
                        type: array
                        example:
                          - id: 1
                            name: Hot
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Hot
                      assignees:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      followers:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      creator:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      custom_fields:
                        type: object
                        properties:
                          region:
                            type: string
                            example: Asia
                      created_at:
                        type: string
                        example: '2026-08-06T12:11:37+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-11T06:18:26+00:00'
        404:
          description: 'Lead not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Lead not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Lead not found.'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      title:
                        - 'The title field must be a string.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          title:
                            type: array
                            example:
                              - 'The title field must be a string.'
                            items:
                              type: string
      tags:
        - Leads
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: 'The lead title.'
                  example: 'Acme Corp renewal (updated)'
                value:
                  type: number
                  description: 'The monetary value of the lead.'
                  example: 7500.0
                currency:
                  type: string
                  description: "ISO 4217 currency code. Defaults to the account's base currency when the request also sets `value` and omits `currency`."
                  example: USD
                exchange_rate:
                  type: number
                  description: "Exchange rate to the account's base currency."
                  example: 1.0
                expected_close_date:
                  type: string
                  description: 'Expected close date (Y-m-d).'
                  example: '2026-09-01'
                person:
                  type: string
                  description: "Person's name - matched to an existing Person by exact name, or created if no match."
                  example: 'John Doe'
                organization:
                  type: string
                  description: "Organization's name - matched to an existing Organization by exact name, or created if no match."
                  example: 'Acme Corp'
                status_id:
                  type: integer
                  description: 'Status ID.'
                  example: 1
                source_channel_id:
                  type: integer
                  description: 'Source Channel ID (see GET /source-channels).'
                  example: 1
                source_channel:
                  type: string
                  description: 'Free-text source channel.'
                  example: Referral
                owner_id:
                  type: integer
                  description: 'User ID the lead is assigned to.'
                  example: 1
                labels:
                  type: array
                  description: 'Label IDs to attach (see GET /labels?type=lead).'
                  example:
                    - 1
                    - 2
                  items:
                    type: integer
                assignees:
                  type: array
                  description: 'User IDs assigned to the lead.'
                  example:
                    - 1
                  items:
                    type: integer
                followers:
                  type: array
                  description: 'User IDs following the lead.'
                  example:
                    - 1
                  items:
                    type: integer
    delete:
      summary: 'Delete a lead'
      operationId: deleteALead
      description: 'Soft-deletes the lead, matching the internal delete behavior.'
      parameters: []
      responses:
        204:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {}
                properties: {}
      tags:
        - Leads
    parameters:
      -
        in: path
        name: id
        description: 'The lead ID.'
        example: 42
        required: true
        schema:
          type: integer
  /api/v1/deals:
    get:
      summary: 'List deals'
      operationId: listDeals
      description: "Returns a paginated list of deals, filterable by any combination of the\nparams below. Filters accepting an array (`param[]=`) are OR'd together\nwithin the same param and AND'd with every other param. Any param not\nlisted here - including its singular form like `status` or `person` -\nis silently ignored, not applied.\n\nCustom fields (tenant-specific, configured under Settings > Fields) are\nalso filterable by their slug, e.g. `country=Qatar` does a partial\nmatch; append `_gte`/`_lte` to a numeric or date custom field for range\nfiltering, e.g. `budget_gte=1000`. This suffix behavior only applies to\ncustom fields, not the native params below."
      parameters:
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
            example: 25
        -
          in: query
          name: all
          description: 'When true, returns deals of every status - including archived and won - and ignores `status_id` if also sent.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'When true, returns deals of every status - including archived and won - and ignores `status_id` if also sent.'
            example: true
        -
          in: query
          name: status_id
          description: 'Filter by status ID(s) (see GET /statuses).'
          example:
            - 15
          required: false
          schema:
            type: array
            description: 'Filter by status ID(s) (see GET /statuses).'
            example:
              - 15
            items:
              type: integer
        -
          in: query
          name: archived
          description: 'Include archived (and won) deals instead of excluding them (the default).'
          example: false
          required: false
          schema:
            type: boolean
            description: 'Include archived (and won) deals instead of excluding them (the default).'
            example: false
        -
          in: query
          name: pipeline
          description: 'Filter by Pipeline ID (see GET /pipelines).'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Filter by Pipeline ID (see GET /pipelines).'
            example: 1
        -
          in: query
          name: person_id
          description: 'Filter by linked Person ID(s).'
          example:
            - 9
          required: false
          schema:
            type: array
            description: 'Filter by linked Person ID(s).'
            example:
              - 9
            items:
              type: integer
        -
          in: query
          name: organization_id
          description: 'Filter by linked Organization ID(s).'
          example:
            - 4
          required: false
          schema:
            type: array
            description: 'Filter by linked Organization ID(s).'
            example:
              - 4
            items:
              type: integer
        -
          in: query
          name: owner_id
          description: 'Filter by owner user ID(s).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by owner user ID(s).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: assignees
          description: 'Filter by assigned user ID(s).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by assigned user ID(s).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: followers
          description: 'Filter by following user ID(s).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by following user ID(s).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: source_channel_id
          description: 'Filter by Source Channel ID(s) (see GET /source-channels).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by Source Channel ID(s) (see GET /source-channels).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: labels
          description: 'Filter by Label ID(s) (see GET /labels?type=deal).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by Label ID(s) (see GET /labels?type=deal).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: created_by
          description: 'Filter by creator user ID(s).'
          example:
            - 1
          required: false
          schema:
            type: array
            description: 'Filter by creator user ID(s).'
            example:
              - 1
            items:
              type: integer
        -
          in: query
          name: title
          description: 'Partial, case-insensitive match on the deal title.'
          example: Acme
          required: false
          schema:
            type: string
            description: 'Partial, case-insensitive match on the deal title.'
            example: Acme
        -
          in: query
          name: currency
          description: 'Filter by ISO 4217 currency code(s).'
          example:
            - USD
          required: false
          schema:
            type: array
            description: 'Filter by ISO 4217 currency code(s).'
            example:
              - USD
            items:
              type: string
        -
          in: query
          name: value_in_base_currency
          description: "numeric[] `[min]` for a lower bound, or `[min,max]` for a range, on value converted to the account's base currency."
          example: 0
          required: false
          schema:
            type: integer
            description: "numeric[] `[min]` for a lower bound, or `[min,max]` for a range, on value converted to the account's base currency."
            example: 0
        -
          in: query
          name: expected_close_date
          description: '`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).'
          example:
            - '2026-09-01'
          required: false
          schema:
            type: array
            description: '`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).'
            example:
              - '2026-09-01'
            items:
              type: string
        -
          in: query
          name: created_at
          description: '`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).'
          example:
            - '2026-01-01'
            - '2026-08-01'
          required: false
          schema:
            type: array
            description: '`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).'
            example:
              - '2026-01-01'
              - '2026-08-01'
            items:
              type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 7
                      title: 'Acme Corp expansion'
                      value: '12000.00'
                      currency: USD
                      value_in_base_currency: '12000.00'
                      expected_close_date: '2026-09-01'
                      status:
                        id: 15
                        name: Open
                        slug: deal-open
                      pipeline:
                        id: 1
                        name: 'Deal Flow'
                      pipeline_stage:
                        id: 1
                        name: Qualified
                      closed_reason: null
                      closed_reason_note: null
                      person:
                        id: 9
                        name: 'John Doe'
                      organization:
                        id: 4
                        name: 'Acme Corp'
                      owner:
                        id: 1
                        name: 'Jane Owner'
                      source_channel: Referral
                      source_channel_id: 1
                      exchange_rate: null
                      labels:
                        -
                          id: 1
                          name: Hot
                      assignees:
                        -
                          id: 1
                          name: 'Jane Owner'
                      followers:
                        -
                          id: 1
                          name: 'Jane Owner'
                      creator:
                        id: 1
                        name: 'Jane Owner'
                      custom_fields:
                        country: Qatar
                      created_at: '2026-08-06T11:42:43+00:00'
                      updated_at: '2026-08-06T11:43:16+00:00'
                  links:
                    first: 'https://{your-subdomain}.saleskey.ai/api/v1/deals?per_page=25&page=1'
                    last: 'https://{your-subdomain}.saleskey.ai/api/v1/deals?per_page=25&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    per_page: 25
                    to: 1
                    total: 1
                    path: 'https://{your-subdomain}.saleskey.ai/api/v1/deals'
                    links:
                      -
                        url: null
                        label: '« Previous'
                        page: null
                        active: false
                      -
                        url: 'https://{your-subdomain}.saleskey.ai/api/v1/deals?per_page=25&page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next »'
                        page: null
                        active: false
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 7
                        title: 'Acme Corp expansion'
                        value: '12000.00'
                        currency: USD
                        value_in_base_currency: '12000.00'
                        expected_close_date: '2026-09-01'
                        status:
                          id: 15
                          name: Open
                          slug: deal-open
                        pipeline:
                          id: 1
                          name: 'Deal Flow'
                        pipeline_stage:
                          id: 1
                          name: Qualified
                        closed_reason: null
                        closed_reason_note: null
                        person:
                          id: 9
                          name: 'John Doe'
                        organization:
                          id: 4
                          name: 'Acme Corp'
                        owner:
                          id: 1
                          name: 'Jane Owner'
                        source_channel: Referral
                        source_channel_id: 1
                        exchange_rate: null
                        labels:
                          - id: 1
                            name: Hot
                        assignees:
                          - id: 1
                            name: 'Jane Owner'
                        followers:
                          - id: 1
                            name: 'Jane Owner'
                        creator:
                          id: 1
                          name: 'Jane Owner'
                        custom_fields:
                          country: Qatar
                        created_at: '2026-08-06T11:42:43+00:00'
                        updated_at: '2026-08-06T11:43:16+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 7
                        title:
                          type: string
                          example: 'Acme Corp expansion'
                        value:
                          type: string
                          example: '12000.00'
                        currency:
                          type: string
                          example: USD
                        value_in_base_currency:
                          type: string
                          example: '12000.00'
                        expected_close_date:
                          type: string
                          example: '2026-09-01'
                        status:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 15
                            name:
                              type: string
                              example: Open
                            slug:
                              type: string
                              example: deal-open
                        pipeline:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Deal Flow'
                        pipeline_stage:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Qualified
                        closed_reason:
                          type: string
                          example: null
                          nullable: true
                        closed_reason_note:
                          type: string
                          example: null
                          nullable: true
                        person:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 9
                            name:
                              type: string
                              example: 'John Doe'
                        organization:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 4
                            name:
                              type: string
                              example: 'Acme Corp'
                        owner:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                        source_channel:
                          type: string
                          example: Referral
                        source_channel_id:
                          type: integer
                          example: 1
                        exchange_rate:
                          type: string
                          example: null
                          nullable: true
                        labels:
                          type: array
                          example:
                            - id: 1
                              name: Hot
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              name:
                                type: string
                                example: Hot
                        assignees:
                          type: array
                          example:
                            - id: 1
                              name: 'Jane Owner'
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              name:
                                type: string
                                example: 'Jane Owner'
                        followers:
                          type: array
                          example:
                            - id: 1
                              name: 'Jane Owner'
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              name:
                                type: string
                                example: 'Jane Owner'
                        creator:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                        custom_fields:
                          type: object
                          properties:
                            country:
                              type: string
                              example: Qatar
                        created_at:
                          type: string
                          example: '2026-08-06T11:42:43+00:00'
                        updated_at:
                          type: string
                          example: '2026-08-06T11:43:16+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/deals?per_page=25&page=1'
                      last:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/deals?per_page=25&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 25
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/deals'
                      links:
                        type: array
                        example:
                          - url: null
                            label: '« Previous'
                            page: null
                            active: false
                          - url: 'https://{your-subdomain}.saleskey.ai/api/v1/deals?per_page=25&page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next »'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '« Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'deals'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'deals'."
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - Deals
    post:
      summary: 'Create a deal'
      operationId: createADeal
      description: "`title` is the only required field. Every other field is optional.\n`pipeline_id` and `pipeline_stage_id` default independently when\nomitted: a missing `pipeline_id` resolves to the tenant's default\n(first active) pipeline; a missing `pipeline_stage_id` resolves to the\nfirst stage of whichever pipeline was used (the one you passed, or the\ndefault) - so passing `pipeline_id` alone still picks that specific\npipeline's first stage, not the tenant default's.\n\nPass `lead_id` to convert an existing Lead into this Deal - the source\nLead is marked converted, and its linked emails are copied over, exactly\nas when converting a lead from the app itself.\n\n`person` and `organization` are plain names, not IDs. Each is matched\nagainst existing records by an exact, case-insensitive name match. If\nfound, the deal is linked to that existing record; if not found, a new\nrecord is created with just that name. Any other field not listed\nbelow is stored as a custom field."
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 8
                    title: 'Acme Corp expansion'
                    value: '12000.00'
                    currency: USD
                    value_in_base_currency: '12000.00'
                    expected_close_date: null
                    status:
                      id: 15
                      name: Open
                      slug: deal-open
                    pipeline:
                      id: 1
                      name: 'Deal Flow'
                    pipeline_stage:
                      id: 1
                      name: Qualified
                    closed_reason: null
                    closed_reason_note: null
                    person:
                      id: 9
                      name: 'John Doe'
                    organization:
                      id: 4
                      name: 'Acme Corp'
                    owner:
                      id: 1
                      name: 'Jane Owner'
                    source_channel: null
                    source_channel_id: null
                    exchange_rate: null
                    labels: []
                    assignees: []
                    followers: []
                    creator:
                      id: 1
                      name: 'Jane Owner'
                    custom_fields: null
                    created_at: '2026-08-06T11:42:43+00:00'
                    updated_at: '2026-08-06T11:42:43+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 8
                      title:
                        type: string
                        example: 'Acme Corp expansion'
                      value:
                        type: string
                        example: '12000.00'
                      currency:
                        type: string
                        example: USD
                      value_in_base_currency:
                        type: string
                        example: '12000.00'
                      expected_close_date:
                        type: string
                        example: null
                        nullable: true
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 15
                          name:
                            type: string
                            example: Open
                          slug:
                            type: string
                            example: deal-open
                      pipeline:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Deal Flow'
                      pipeline_stage:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: Qualified
                      closed_reason:
                        type: string
                        example: null
                        nullable: true
                      closed_reason_note:
                        type: string
                        example: null
                        nullable: true
                      person:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: 'John Doe'
                      organization:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 4
                          name:
                            type: string
                            example: 'Acme Corp'
                      owner:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      source_channel:
                        type: string
                        example: null
                        nullable: true
                      source_channel_id:
                        type: string
                        example: null
                        nullable: true
                      exchange_rate:
                        type: string
                        example: null
                        nullable: true
                      labels:
                        type: array
                        example: []
                      assignees:
                        type: array
                        example: []
                      followers:
                        type: array
                        example: []
                      creator:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      custom_fields:
                        type: string
                        example: null
                        nullable: true
                      created_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      title:
                        - 'The title field is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          title:
                            type: array
                            example:
                              - 'The title field is required.'
                            items:
                              type: string
      tags:
        - Deals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: 'The deal title.'
                  example: 'Acme Corp expansion'
                value:
                  type: number
                  description: 'The monetary value of the deal.'
                  example: 12000.0
                currency:
                  type: string
                  description: "ISO 4217 currency code. Defaults to the account's base currency when omitted."
                  example: USD
                exchange_rate:
                  type: number
                  description: "Exchange rate to the account's base currency. Required when `currency` differs from the base currency."
                  example: 1.0
                expected_close_date:
                  type: string
                  description: 'Expected close date (Y-m-d).'
                  example: '2026-09-01'
                pipeline_id:
                  type: integer
                  description: "Defaults to the tenant's default pipeline if omitted."
                  example: 1
                pipeline_stage_id:
                  type: integer
                  description: "Defaults to the resolved pipeline's first stage if omitted."
                  example: 3
                lead_id:
                  type: integer
                  description: 'Convert this Lead into the new Deal.'
                  example: 42
                person:
                  type: string
                  description: "Person's name - matched to an existing Person by exact name, or created if no match."
                  example: 'John Doe'
                organization:
                  type: string
                  description: "Organization's name - matched to an existing Organization by exact name, or created if no match."
                  example: 'Acme Corp'
                status_id:
                  type: integer
                  description: "Status ID. Defaults to the account's default deal status."
                  example: 1
                source_channel_id:
                  type: integer
                  description: 'Source Channel ID (see GET /source-channels).'
                  example: 1
                source_channel:
                  type: string
                  description: 'Free-text source channel, independent of source_channel_id.'
                  example: Referral
                owner_id:
                  type: integer
                  description: "User ID the deal is assigned to. Defaults to the API key's creator."
                  example: 1
                labels:
                  type: array
                  description: 'Label IDs to attach (see GET /labels?type=deal).'
                  example:
                    - 1
                    - 2
                  items:
                    type: integer
                assignees:
                  type: array
                  description: 'User IDs assigned to the deal.'
                  example:
                    - 1
                  items:
                    type: integer
                followers:
                  type: array
                  description: 'User IDs following the deal.'
                  example:
                    - 1
                  items:
                    type: integer
              required:
                - title
  '/api/v1/deals/{id}':
    get:
      summary: 'Retrieve a deal'
      operationId: retrieveADeal
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 7
                    title: 'Acme Corp expansion'
                    value: '12000.00'
                    currency: USD
                    value_in_base_currency: '12000.00'
                    expected_close_date: '2026-09-01'
                    status:
                      id: 15
                      name: Open
                      slug: deal-open
                    pipeline:
                      id: 1
                      name: 'Deal Flow'
                    pipeline_stage:
                      id: 1
                      name: Qualified
                    closed_reason: null
                    closed_reason_note: null
                    person:
                      id: 9
                      name: 'John Doe'
                    organization:
                      id: 4
                      name: 'Acme Corp'
                    owner:
                      id: 1
                      name: 'Jane Owner'
                    source_channel: Referral
                    source_channel_id: 1
                    exchange_rate: null
                    labels:
                      -
                        id: 1
                        name: Hot
                    assignees:
                      -
                        id: 1
                        name: 'Jane Owner'
                    followers:
                      -
                        id: 1
                        name: 'Jane Owner'
                    creator:
                      id: 1
                      name: 'Jane Owner'
                    custom_fields:
                      country: Qatar
                    created_at: '2026-08-06T11:42:43+00:00'
                    updated_at: '2026-08-06T11:43:16+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 7
                      title:
                        type: string
                        example: 'Acme Corp expansion'
                      value:
                        type: string
                        example: '12000.00'
                      currency:
                        type: string
                        example: USD
                      value_in_base_currency:
                        type: string
                        example: '12000.00'
                      expected_close_date:
                        type: string
                        example: '2026-09-01'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 15
                          name:
                            type: string
                            example: Open
                          slug:
                            type: string
                            example: deal-open
                      pipeline:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Deal Flow'
                      pipeline_stage:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: Qualified
                      closed_reason:
                        type: string
                        example: null
                        nullable: true
                      closed_reason_note:
                        type: string
                        example: null
                        nullable: true
                      person:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: 'John Doe'
                      organization:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 4
                          name:
                            type: string
                            example: 'Acme Corp'
                      owner:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      source_channel:
                        type: string
                        example: Referral
                      source_channel_id:
                        type: integer
                        example: 1
                      exchange_rate:
                        type: string
                        example: null
                        nullable: true
                      labels:
                        type: array
                        example:
                          - id: 1
                            name: Hot
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Hot
                      assignees:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      followers:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      creator:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      custom_fields:
                        type: object
                        properties:
                          country:
                            type: string
                            example: Qatar
                      created_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T11:43:16+00:00'
        404:
          description: 'Deal not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Deal not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Deal not found.'
      tags:
        - Deals
    patch:
      summary: 'Update a deal'
      operationId: updateADeal
      description: "Partial update - send only the fields you want to change. Pipeline\nstage cannot be changed here; use the dedicated stage endpoint below.\n\n`person` and `organization` follow the same match-or-create rule as\ncreate: exact, case-insensitive name match against an existing record,\nor a new record is created if no match exists."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 7
                    title: 'Acme Corp expansion (updated)'
                    value: '15000.00'
                    currency: USD
                    value_in_base_currency: '15000.00'
                    expected_close_date: '2026-09-01'
                    status:
                      id: 15
                      name: Open
                      slug: deal-open
                    pipeline:
                      id: 1
                      name: 'Deal Flow'
                    pipeline_stage:
                      id: 1
                      name: Qualified
                    closed_reason: null
                    closed_reason_note: null
                    person:
                      id: 9
                      name: 'John Doe'
                    organization:
                      id: 4
                      name: 'Acme Corp'
                    owner:
                      id: 1
                      name: 'Jane Owner'
                    source_channel: Referral
                    source_channel_id: 1
                    exchange_rate: null
                    labels:
                      -
                        id: 1
                        name: Hot
                    assignees:
                      -
                        id: 1
                        name: 'Jane Owner'
                    followers:
                      -
                        id: 1
                        name: 'Jane Owner'
                    creator:
                      id: 1
                      name: 'Jane Owner'
                    custom_fields:
                      country: Qatar
                    created_at: '2026-08-06T11:42:43+00:00'
                    updated_at: '2026-08-11T06:30:44+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 7
                      title:
                        type: string
                        example: 'Acme Corp expansion (updated)'
                      value:
                        type: string
                        example: '15000.00'
                      currency:
                        type: string
                        example: USD
                      value_in_base_currency:
                        type: string
                        example: '15000.00'
                      expected_close_date:
                        type: string
                        example: '2026-09-01'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 15
                          name:
                            type: string
                            example: Open
                          slug:
                            type: string
                            example: deal-open
                      pipeline:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Deal Flow'
                      pipeline_stage:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: Qualified
                      closed_reason:
                        type: string
                        example: null
                        nullable: true
                      closed_reason_note:
                        type: string
                        example: null
                        nullable: true
                      person:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: 'John Doe'
                      organization:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 4
                          name:
                            type: string
                            example: 'Acme Corp'
                      owner:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      source_channel:
                        type: string
                        example: Referral
                      source_channel_id:
                        type: integer
                        example: 1
                      exchange_rate:
                        type: string
                        example: null
                        nullable: true
                      labels:
                        type: array
                        example:
                          - id: 1
                            name: Hot
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Hot
                      assignees:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      followers:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      creator:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      custom_fields:
                        type: object
                        properties:
                          country:
                            type: string
                            example: Qatar
                      created_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-11T06:30:44+00:00'
        404:
          description: 'Deal not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Deal not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Deal not found.'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      pipeline_stage_id:
                        - 'Stage cannot be changed here - use PATCH /deals/{id}/stage instead.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          pipeline_stage_id:
                            type: array
                            example:
                              - 'Stage cannot be changed here - use PATCH /deals/{id}/stage instead.'
                            items:
                              type: string
      tags:
        - Deals
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: 'The deal title.'
                  example: 'Acme Corp expansion (updated)'
                value:
                  type: number
                  description: 'The monetary value of the deal.'
                  example: 15000.0
                currency:
                  type: string
                  description: "ISO 4217 currency code. Defaults to the account's base currency when the request also sets `value` and omits `currency`."
                  example: USD
                exchange_rate:
                  type: number
                  description: "Exchange rate to the account's base currency."
                  example: 1.0
                person:
                  type: string
                  description: "Person's name - matched to an existing Person by exact name, or created if no match."
                  example: 'John Doe'
                organization:
                  type: string
                  description: "Organization's name - matched to an existing Organization by exact name, or created if no match."
                  example: 'Acme Corp'
                status_id:
                  type: integer
                  description: 'Status ID.'
                  example: 1
                source_channel_id:
                  type: integer
                  description: 'Source Channel ID (see GET /source-channels).'
                  example: 1
                source_channel:
                  type: string
                  description: 'Free-text source channel.'
                  example: Referral
                owner_id:
                  type: integer
                  description: 'User ID the deal is assigned to.'
                  example: 1
                labels:
                  type: array
                  description: 'Label IDs to attach (see GET /labels?type=deal).'
                  example:
                    - 1
                    - 2
                  items:
                    type: integer
                assignees:
                  type: array
                  description: 'User IDs assigned to the deal.'
                  example:
                    - 1
                  items:
                    type: integer
                followers:
                  type: array
                  description: 'User IDs following the deal.'
                  example:
                    - 1
                  items:
                    type: integer
    delete:
      summary: 'Delete a deal'
      operationId: deleteADeal
      description: 'Soft-deletes the deal, matching the internal delete behavior.'
      parameters: []
      responses:
        204:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {}
                properties: {}
      tags:
        - Deals
    parameters:
      -
        in: path
        name: id
        description: 'The deal ID.'
        example: 7
        required: true
        schema:
          type: integer
  '/api/v1/deals/{id}/stage':
    patch:
      summary: "Change a deal's stage"
      operationId: changeADealsStage
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 7
                    title: 'Acme Corp expansion'
                    value: '12000.00'
                    currency: USD
                    value_in_base_currency: '12000.00'
                    expected_close_date: '2026-09-01'
                    status:
                      id: 15
                      name: Open
                      slug: deal-open
                    pipeline:
                      id: 1
                      name: 'Deal Flow'
                    pipeline_stage:
                      id: 2
                      name: 'Contact Made'
                    closed_reason: null
                    closed_reason_note: null
                    person:
                      id: 9
                      name: 'John Doe'
                    organization:
                      id: 4
                      name: 'Acme Corp'
                    owner:
                      id: 1
                      name: 'Jane Owner'
                    source_channel: Referral
                    source_channel_id: 1
                    exchange_rate: null
                    labels:
                      -
                        id: 1
                        name: Hot
                    assignees:
                      -
                        id: 1
                        name: 'Jane Owner'
                    followers:
                      -
                        id: 1
                        name: 'Jane Owner'
                    creator:
                      id: 1
                      name: 'Jane Owner'
                    custom_fields:
                      country: Qatar
                    created_at: '2026-08-06T11:42:43+00:00'
                    updated_at: '2026-08-11T06:31:00+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 7
                      title:
                        type: string
                        example: 'Acme Corp expansion'
                      value:
                        type: string
                        example: '12000.00'
                      currency:
                        type: string
                        example: USD
                      value_in_base_currency:
                        type: string
                        example: '12000.00'
                      expected_close_date:
                        type: string
                        example: '2026-09-01'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 15
                          name:
                            type: string
                            example: Open
                          slug:
                            type: string
                            example: deal-open
                      pipeline:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Deal Flow'
                      pipeline_stage:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 2
                          name:
                            type: string
                            example: 'Contact Made'
                      closed_reason:
                        type: string
                        example: null
                        nullable: true
                      closed_reason_note:
                        type: string
                        example: null
                        nullable: true
                      person:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: 'John Doe'
                      organization:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 4
                          name:
                            type: string
                            example: 'Acme Corp'
                      owner:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      source_channel:
                        type: string
                        example: Referral
                      source_channel_id:
                        type: integer
                        example: 1
                      exchange_rate:
                        type: string
                        example: null
                        nullable: true
                      labels:
                        type: array
                        example:
                          - id: 1
                            name: Hot
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Hot
                      assignees:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      followers:
                        type: array
                        example:
                          - id: 1
                            name: 'Jane Owner'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Jane Owner'
                      creator:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Owner'
                      custom_fields:
                        type: object
                        properties:
                          country:
                            type: string
                            example: Qatar
                      created_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-11T06:31:00+00:00'
        404:
          description: 'Deal not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Deal not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Deal not found.'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      pipeline_stage_id:
                        - 'The selected pipeline stage id is invalid.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          pipeline_stage_id:
                            type: array
                            example:
                              - 'The selected pipeline stage id is invalid.'
                            items:
                              type: string
      tags:
        - Deals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pipeline_stage_id:
                  type: integer
                  description: 'The target stage ID.'
                  example: 3
                pipeline_id:
                  type: integer
                  description: 'Only needed when also moving to a different pipeline.'
                  example: 1
                  nullable: true
              required:
                - pipeline_stage_id
    parameters:
      -
        in: path
        name: id
        description: 'The deal ID.'
        example: 7
        required: true
        schema:
          type: integer
  /api/v1/people:
    get:
      summary: 'List people'
      operationId: listPeople
      description: "Returns a paginated list of people. Supports `page`, `per_page`, and the\nsame filters as the web app."
      parameters:
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
            example: 25
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 9
                      name: 'John Doe'
                      first_name: John
                      last_name: Doe
                      email:
                        -
                          label: Work
                          value: john.doe@example.com
                      phone:
                        -
                          label: Mobile
                          value: '+17703505963'
                      status:
                        id: 9
                        name: Lead
                        slug: contact-lead
                      organizations:
                        -
                          id: 4
                          name: 'Acme Corp'
                      custom_fields:
                        region: Asia
                      created_at: '2026-08-06T12:11:37+00:00'
                      updated_at: '2026-08-06T12:11:37+00:00'
                  links:
                    first: 'https://{your-subdomain}.saleskey.ai/api/v1/people?per_page=25&page=1'
                    last: 'https://{your-subdomain}.saleskey.ai/api/v1/people?per_page=25&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    per_page: 25
                    to: 1
                    total: 1
                    path: 'https://{your-subdomain}.saleskey.ai/api/v1/people'
                    links:
                      -
                        url: null
                        label: '« Previous'
                        page: null
                        active: false
                      -
                        url: 'https://{your-subdomain}.saleskey.ai/api/v1/people?per_page=25&page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next »'
                        page: null
                        active: false
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 9
                        name: 'John Doe'
                        first_name: John
                        last_name: Doe
                        email:
                          - label: Work
                            value: john.doe@example.com
                        phone:
                          - label: Mobile
                            value: '+17703505963'
                        status:
                          id: 9
                          name: Lead
                          slug: contact-lead
                        organizations:
                          - id: 4
                            name: 'Acme Corp'
                        custom_fields:
                          region: Asia
                        created_at: '2026-08-06T12:11:37+00:00'
                        updated_at: '2026-08-06T12:11:37+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 9
                        name:
                          type: string
                          example: 'John Doe'
                        first_name:
                          type: string
                          example: John
                        last_name:
                          type: string
                          example: Doe
                        email:
                          type: array
                          example:
                            - label: Work
                              value: john.doe@example.com
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                                example: Work
                              value:
                                type: string
                                example: john.doe@example.com
                        phone:
                          type: array
                          example:
                            - label: Mobile
                              value: '+17703505963'
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                                example: Mobile
                              value:
                                type: string
                                example: '+17703505963'
                        status:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 9
                            name:
                              type: string
                              example: Lead
                            slug:
                              type: string
                              example: contact-lead
                        organizations:
                          type: array
                          example:
                            - id: 4
                              name: 'Acme Corp'
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 4
                              name:
                                type: string
                                example: 'Acme Corp'
                        custom_fields:
                          type: object
                          properties:
                            region:
                              type: string
                              example: Asia
                        created_at:
                          type: string
                          example: '2026-08-06T12:11:37+00:00'
                        updated_at:
                          type: string
                          example: '2026-08-06T12:11:37+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/people?per_page=25&page=1'
                      last:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/people?per_page=25&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 25
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/people'
                      links:
                        type: array
                        example:
                          - url: null
                            label: '« Previous'
                            page: null
                            active: false
                          - url: 'https://{your-subdomain}.saleskey.ai/api/v1/people?per_page=25&page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next »'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '« Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'people'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'people'."
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - People
    post:
      summary: 'Create a person'
      operationId: createAPerson
      description: "`name` is the only required field. Every other field - email, phone,\nstatus, custom fields - is optional and will be left empty or defaulted\n(status defaults to the account's default contact status) if omitted.\n\nPass `organization` to attach a Person's Organization - a plain name,\nmatched by exact, case-insensitive name against an existing\nOrganization (attached if found), or created if no match exists. A\nPerson's organization is a many-to-many link, not a single field."
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 9
                    name: 'Jane Doe'
                    first_name: Jane
                    last_name: Doe
                    email: null
                    phone: null
                    status:
                      id: 9
                      name: Lead
                      slug: contact-lead
                    organizations: []
                    custom_fields: null
                    created_at: '2026-08-06T12:11:37+00:00'
                    updated_at: '2026-08-06T12:11:37+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 9
                      name:
                        type: string
                        example: 'Jane Doe'
                      first_name:
                        type: string
                        example: Jane
                      last_name:
                        type: string
                        example: Doe
                      email:
                        type: string
                        example: null
                        nullable: true
                      phone:
                        type: string
                        example: null
                        nullable: true
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: Lead
                          slug:
                            type: string
                            example: contact-lead
                      organizations:
                        type: array
                        example: []
                      custom_fields:
                        type: string
                        example: null
                        nullable: true
                      created_at:
                        type: string
                        example: '2026-08-06T12:11:37+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T12:11:37+00:00'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      name:
                        - 'The name field is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          name:
                            type: array
                            example:
                              - 'The name field is required.'
                            items:
                              type: string
      tags:
        - People
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: "The person's full name."
                  example: 'Jane Doe'
                organization:
                  type: string
                  description: 'Organization name - matched to an existing Organization by exact name, or created if no match.'
                  example: 'Acme Corp'
              required:
                - name
  '/api/v1/people/{id}':
    get:
      summary: 'Retrieve a person'
      operationId: retrieveAPerson
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 9
                    name: 'John Doe'
                    first_name: John
                    last_name: Doe
                    email:
                      -
                        label: Work
                        value: john.doe@example.com
                    phone:
                      -
                        label: Mobile
                        value: '+17703505963'
                    status:
                      id: 9
                      name: Lead
                      slug: contact-lead
                    organizations:
                      -
                        id: 4
                        name: 'Acme Corp'
                    custom_fields:
                      region: Asia
                    created_at: '2026-08-06T12:11:37+00:00'
                    updated_at: '2026-08-06T12:11:37+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 9
                      name:
                        type: string
                        example: 'John Doe'
                      first_name:
                        type: string
                        example: John
                      last_name:
                        type: string
                        example: Doe
                      email:
                        type: array
                        example:
                          - label: Work
                            value: john.doe@example.com
                        items:
                          type: object
                          properties:
                            label:
                              type: string
                              example: Work
                            value:
                              type: string
                              example: john.doe@example.com
                      phone:
                        type: array
                        example:
                          - label: Mobile
                            value: '+17703505963'
                        items:
                          type: object
                          properties:
                            label:
                              type: string
                              example: Mobile
                            value:
                              type: string
                              example: '+17703505963'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: Lead
                          slug:
                            type: string
                            example: contact-lead
                      organizations:
                        type: array
                        example:
                          - id: 4
                            name: 'Acme Corp'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 4
                            name:
                              type: string
                              example: 'Acme Corp'
                      custom_fields:
                        type: object
                        properties:
                          region:
                            type: string
                            example: Asia
                      created_at:
                        type: string
                        example: '2026-08-06T12:11:37+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T12:11:37+00:00'
        404:
          description: 'Person not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Person not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Person not found.'
      tags:
        - People
    patch:
      summary: 'Update a person'
      operationId: updateAPerson
      description: "Partial update - send only the fields you want to change. Unlike the\ninternal app's edit form, `organization` can be sent alongside other\nfields in the same request; the organization link is replaced (not\nadded to) when provided. It follows the same match-or-create rule as\ncreate: exact, case-insensitive name match against an existing\nOrganization, or a new one is created if no match exists."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 9
                    name: 'Jane Doe (updated)'
                    first_name: Jane
                    last_name: 'Doe (updated)'
                    email: null
                    phone: null
                    status:
                      id: 9
                      name: Lead
                      slug: contact-lead
                    organizations:
                      -
                        id: 4
                        name: 'Acme Corp'
                    custom_fields: null
                    created_at: '2026-08-06T09:26:59+00:00'
                    updated_at: '2026-08-06T11:46:04+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 9
                      name:
                        type: string
                        example: 'Jane Doe (updated)'
                      first_name:
                        type: string
                        example: Jane
                      last_name:
                        type: string
                        example: 'Doe (updated)'
                      email:
                        type: string
                        example: null
                        nullable: true
                      phone:
                        type: string
                        example: null
                        nullable: true
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 9
                          name:
                            type: string
                            example: Lead
                          slug:
                            type: string
                            example: contact-lead
                      organizations:
                        type: array
                        example:
                          - id: 4
                            name: 'Acme Corp'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 4
                            name:
                              type: string
                              example: 'Acme Corp'
                      custom_fields:
                        type: string
                        example: null
                        nullable: true
                      created_at:
                        type: string
                        example: '2026-08-06T09:26:59+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T11:46:04+00:00'
        404:
          description: 'Person not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Person not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Person not found.'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      name:
                        - 'The name field must be a string.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          name:
                            type: array
                            example:
                              - 'The name field must be a string.'
                            items:
                              type: string
      tags:
        - People
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: "The person's full name."
                  example: 'Jane Doe (updated)'
                organization:
                  type: string
                  description: 'Replace the attached Organization - matched to an existing Organization by exact name, or created if no match.'
                  example: 'Acme Corp'
    delete:
      summary: 'Delete a person'
      operationId: deleteAPerson
      description: 'Soft-deletes the person, matching the internal delete behavior.'
      parameters: []
      responses:
        204:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {}
                properties: {}
      tags:
        - People
    parameters:
      -
        in: path
        name: id
        description: 'The person ID.'
        example: 9
        required: true
        schema:
          type: integer
  /api/v1/organizations:
    get:
      summary: 'List organizations'
      operationId: listOrganizations
      description: "Returns a paginated list of organizations. Supports `page`, `per_page`,\nand the same filters as the web app."
      parameters:
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
            example: 25
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 4
                      name: 'Acme Corp'
                      email: info@acme.test
                      phone: '+13947741292'
                      website: 'https://acme.test'
                      street_address: '3944 Broadway'
                      city: Phoenix
                      state: AZ
                      postal_code: '27434'
                      country: 'United States'
                      status:
                        id: 11
                        name: 'In Deal'
                        slug: contact-in-deal
                      people:
                        -
                          id: 9
                          name: 'John Doe'
                      custom_fields:
                        industry: SaaS
                      created_at: '2026-08-05T07:05:52+00:00'
                      updated_at: '2026-08-06T11:42:43+00:00'
                  links:
                    first: 'https://{your-subdomain}.saleskey.ai/api/v1/organizations?per_page=25&page=1'
                    last: 'https://{your-subdomain}.saleskey.ai/api/v1/organizations?per_page=25&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    per_page: 25
                    to: 1
                    total: 1
                    path: 'https://{your-subdomain}.saleskey.ai/api/v1/organizations'
                    links:
                      -
                        url: null
                        label: '« Previous'
                        page: null
                        active: false
                      -
                        url: 'https://{your-subdomain}.saleskey.ai/api/v1/organizations?per_page=25&page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next »'
                        page: null
                        active: false
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 4
                        name: 'Acme Corp'
                        email: info@acme.test
                        phone: '+13947741292'
                        website: 'https://acme.test'
                        street_address: '3944 Broadway'
                        city: Phoenix
                        state: AZ
                        postal_code: '27434'
                        country: 'United States'
                        status:
                          id: 11
                          name: 'In Deal'
                          slug: contact-in-deal
                        people:
                          - id: 9
                            name: 'John Doe'
                        custom_fields:
                          industry: SaaS
                        created_at: '2026-08-05T07:05:52+00:00'
                        updated_at: '2026-08-06T11:42:43+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 4
                        name:
                          type: string
                          example: 'Acme Corp'
                        email:
                          type: string
                          example: info@acme.test
                        phone:
                          type: string
                          example: '+13947741292'
                        website:
                          type: string
                          example: 'https://acme.test'
                        street_address:
                          type: string
                          example: '3944 Broadway'
                        city:
                          type: string
                          example: Phoenix
                        state:
                          type: string
                          example: AZ
                        postal_code:
                          type: string
                          example: '27434'
                        country:
                          type: string
                          example: 'United States'
                        status:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 11
                            name:
                              type: string
                              example: 'In Deal'
                            slug:
                              type: string
                              example: contact-in-deal
                        people:
                          type: array
                          example:
                            - id: 9
                              name: 'John Doe'
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 9
                              name:
                                type: string
                                example: 'John Doe'
                        custom_fields:
                          type: object
                          properties:
                            industry:
                              type: string
                              example: SaaS
                        created_at:
                          type: string
                          example: '2026-08-05T07:05:52+00:00'
                        updated_at:
                          type: string
                          example: '2026-08-06T11:42:43+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/organizations?per_page=25&page=1'
                      last:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/organizations?per_page=25&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 25
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/organizations'
                      links:
                        type: array
                        example:
                          - url: null
                            label: '« Previous'
                            page: null
                            active: false
                          - url: 'https://{your-subdomain}.saleskey.ai/api/v1/organizations?per_page=25&page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next »'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '« Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'organizations'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'organizations'."
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - Organizations
    post:
      summary: 'Create an organization'
      operationId: createAnOrganization
      description: "`name` is the only required field. Every other field is optional. Note:\n`status_id` cannot be set on create - it always defaults to the\naccount's default contact status, matching the internal app's existing\nbehavior. To attach people to the organization, use the dedicated\nlink-person endpoint below after creation."
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 4
                    name: 'Acme Corp'
                    email: null
                    phone: null
                    website: 'https://acme.test'
                    street_address: null
                    city: null
                    state: null
                    postal_code: null
                    country: null
                    status:
                      id: 8
                      name: 'Record Only'
                      slug: contact-record-only
                    people: []
                    custom_fields: null
                    created_at: '2026-08-06T11:46:31+00:00'
                    updated_at: '2026-08-06T11:46:31+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 4
                      name:
                        type: string
                        example: 'Acme Corp'
                      email:
                        type: string
                        example: null
                        nullable: true
                      phone:
                        type: string
                        example: null
                        nullable: true
                      website:
                        type: string
                        example: 'https://acme.test'
                      street_address:
                        type: string
                        example: null
                        nullable: true
                      city:
                        type: string
                        example: null
                        nullable: true
                      state:
                        type: string
                        example: null
                        nullable: true
                      postal_code:
                        type: string
                        example: null
                        nullable: true
                      country:
                        type: string
                        example: null
                        nullable: true
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 8
                          name:
                            type: string
                            example: 'Record Only'
                          slug:
                            type: string
                            example: contact-record-only
                      people:
                        type: array
                        example: []
                      custom_fields:
                        type: string
                        example: null
                        nullable: true
                      created_at:
                        type: string
                        example: '2026-08-06T11:46:31+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T11:46:31+00:00'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      name:
                        - 'The name field is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          name:
                            type: array
                            example:
                              - 'The name field is required.'
                            items:
                              type: string
      tags:
        - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: "The organization's name."
                  example: 'Acme Corp'
                website:
                  type: string
                  description: "The organization's website."
                  example: acme.test
              required:
                - name
  '/api/v1/organizations/{id}':
    get:
      summary: 'Retrieve an organization'
      operationId: retrieveAnOrganization
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 4
                    name: 'Acme Corp'
                    email: info@acme.test
                    phone: '+13947741292'
                    website: 'https://acme.test'
                    street_address: '3944 Broadway'
                    city: Phoenix
                    state: AZ
                    postal_code: '27434'
                    country: 'United States'
                    status:
                      id: 11
                      name: 'In Deal'
                      slug: contact-in-deal
                    people:
                      -
                        id: 9
                        name: 'John Doe'
                    custom_fields:
                      industry: SaaS
                    created_at: '2026-08-05T07:05:52+00:00'
                    updated_at: '2026-08-06T11:42:43+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 4
                      name:
                        type: string
                        example: 'Acme Corp'
                      email:
                        type: string
                        example: info@acme.test
                      phone:
                        type: string
                        example: '+13947741292'
                      website:
                        type: string
                        example: 'https://acme.test'
                      street_address:
                        type: string
                        example: '3944 Broadway'
                      city:
                        type: string
                        example: Phoenix
                      state:
                        type: string
                        example: AZ
                      postal_code:
                        type: string
                        example: '27434'
                      country:
                        type: string
                        example: 'United States'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 11
                          name:
                            type: string
                            example: 'In Deal'
                          slug:
                            type: string
                            example: contact-in-deal
                      people:
                        type: array
                        example:
                          - id: 9
                            name: 'John Doe'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 9
                            name:
                              type: string
                              example: 'John Doe'
                      custom_fields:
                        type: object
                        properties:
                          industry:
                            type: string
                            example: SaaS
                      created_at:
                        type: string
                        example: '2026-08-05T07:05:52+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
        404:
          description: 'Organization not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Organization not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Organization not found.'
      tags:
        - Organizations
    patch:
      summary: 'Update an organization'
      operationId: updateAnOrganization
      description: 'Partial update - send only the fields you want to change.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 4
                    name: 'Acme Corp (updated)'
                    email: info@acme.test
                    phone: '+13947741292'
                    website: 'https://acme.test'
                    street_address: '3944 Broadway'
                    city: Phoenix
                    state: AZ
                    postal_code: '27434'
                    country: 'United States'
                    status:
                      id: 11
                      name: 'In Deal'
                      slug: contact-in-deal
                    people:
                      -
                        id: 9
                        name: 'John Doe'
                    custom_fields:
                      industry: SaaS
                    created_at: '2026-08-05T07:05:52+00:00'
                    updated_at: '2026-08-06T11:42:43+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 4
                      name:
                        type: string
                        example: 'Acme Corp (updated)'
                      email:
                        type: string
                        example: info@acme.test
                      phone:
                        type: string
                        example: '+13947741292'
                      website:
                        type: string
                        example: 'https://acme.test'
                      street_address:
                        type: string
                        example: '3944 Broadway'
                      city:
                        type: string
                        example: Phoenix
                      state:
                        type: string
                        example: AZ
                      postal_code:
                        type: string
                        example: '27434'
                      country:
                        type: string
                        example: 'United States'
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 11
                          name:
                            type: string
                            example: 'In Deal'
                          slug:
                            type: string
                            example: contact-in-deal
                      people:
                        type: array
                        example:
                          - id: 9
                            name: 'John Doe'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 9
                            name:
                              type: string
                              example: 'John Doe'
                      custom_fields:
                        type: object
                        properties:
                          industry:
                            type: string
                            example: SaaS
                      created_at:
                        type: string
                        example: '2026-08-05T07:05:52+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
        404:
          description: 'Organization not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Organization not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Organization not found.'
        422:
          description: 'Validation failed'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      name:
                        - 'The name field must be a string.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          name:
                            type: array
                            example:
                              - 'The name field must be a string.'
                            items:
                              type: string
      tags:
        - Organizations
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: "The organization's name."
                  example: 'Acme Corp (updated)'
    delete:
      summary: 'Delete an organization'
      operationId: deleteAnOrganization
      description: 'Soft-deletes the organization, matching the internal delete behavior.'
      parameters: []
      responses:
        204:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {}
                properties: {}
      tags:
        - Organizations
    parameters:
      -
        in: path
        name: id
        description: 'The organization ID.'
        example: 4
        required: true
        schema:
          type: integer
  '/api/v1/organizations/{id}/people':
    post:
      summary: 'Link a person to an organization'
      operationId: linkAPersonToAnOrganization
      description: "`person` is a plain name - matched by exact, case-insensitive name\nagainst an existing Person (attached if found), or created and\nattached if no match exists."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 4
                    name: 'Acme Corp'
                    email: null
                    phone: null
                    website: 'https://acme.test'
                    street_address: null
                    city: null
                    state: null
                    postal_code: null
                    country: null
                    status:
                      id: 11
                      name: 'In Deal'
                      slug: contact-in-deal
                    people:
                      -
                        id: 9
                        name: 'Jane Doe'
                    custom_fields: null
                    created_at: '2026-08-05T07:05:52+00:00'
                    updated_at: '2026-08-06T11:42:43+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 4
                      name:
                        type: string
                        example: 'Acme Corp'
                      email:
                        type: string
                        example: null
                        nullable: true
                      phone:
                        type: string
                        example: null
                        nullable: true
                      website:
                        type: string
                        example: 'https://acme.test'
                      street_address:
                        type: string
                        example: null
                        nullable: true
                      city:
                        type: string
                        example: null
                        nullable: true
                      state:
                        type: string
                        example: null
                        nullable: true
                      postal_code:
                        type: string
                        example: null
                        nullable: true
                      country:
                        type: string
                        example: null
                        nullable: true
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 11
                          name:
                            type: string
                            example: 'In Deal'
                          slug:
                            type: string
                            example: contact-in-deal
                      people:
                        type: array
                        example:
                          - id: 9
                            name: 'Jane Doe'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 9
                            name:
                              type: string
                              example: 'Jane Doe'
                      custom_fields:
                        type: string
                        example: null
                        nullable: true
                      created_at:
                        type: string
                        example: '2026-08-05T07:05:52+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
        404:
          description: 'Organization not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Organization not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Organization not found.'
      tags:
        - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                person:
                  type: string
                  description: "Person's name - matched to an existing Person by exact name, or created if no match."
                  example: 'Jane Doe'
              required:
                - person
    parameters:
      -
        in: path
        name: id
        description: 'The organization ID.'
        example: 4
        required: true
        schema:
          type: integer
  '/api/v1/organizations/{id}/people/{personId}':
    delete:
      summary: 'Unlink a person from an organization'
      operationId: unlinkAPersonFromAnOrganization
      description: 'Detaches the person without deleting the Person record itself.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 4
                    name: 'Acme Corp'
                    email: null
                    phone: null
                    website: 'https://acme.test'
                    street_address: null
                    city: null
                    state: null
                    postal_code: null
                    country: null
                    status:
                      id: 11
                      name: 'In Deal'
                      slug: contact-in-deal
                    people: []
                    custom_fields: null
                    created_at: '2026-08-05T07:05:52+00:00'
                    updated_at: '2026-08-06T11:42:43+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 4
                      name:
                        type: string
                        example: 'Acme Corp'
                      email:
                        type: string
                        example: null
                        nullable: true
                      phone:
                        type: string
                        example: null
                        nullable: true
                      website:
                        type: string
                        example: 'https://acme.test'
                      street_address:
                        type: string
                        example: null
                        nullable: true
                      city:
                        type: string
                        example: null
                        nullable: true
                      state:
                        type: string
                        example: null
                        nullable: true
                      postal_code:
                        type: string
                        example: null
                        nullable: true
                      country:
                        type: string
                        example: null
                        nullable: true
                      status:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 11
                          name:
                            type: string
                            example: 'In Deal'
                          slug:
                            type: string
                            example: contact-in-deal
                      people:
                        type: array
                        example: []
                      custom_fields:
                        type: string
                        example: null
                        nullable: true
                      created_at:
                        type: string
                        example: '2026-08-05T07:05:52+00:00'
                      updated_at:
                        type: string
                        example: '2026-08-06T11:42:43+00:00'
        404:
          description: 'Organization not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Organization not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Organization not found.'
      tags:
        - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                person_id:
                  type: integer
                  description: 'Must match an existing stored value.'
                  example: 16
              required:
                - person_id
    parameters:
      -
        in: path
        name: id
        description: 'The organization ID.'
        example: 4
        required: true
        schema:
          type: integer
      -
        in: path
        name: personId
        description: 'The person ID to unlink.'
        example: 9
        required: true
        schema:
          type: integer
  /api/v1/statuses:
    get:
      summary: 'List statuses'
      operationId: listStatuses
      description: "Returns the statuses defined for a single type, ordered the same way\nthey appear in the Settings UI. `type=contact` covers both People and\nOrganizations - there's no separate `person`/`organization` type."
      parameters:
        -
          in: query
          name: type
          description: 'One of: lead, contact, deal, project. `contact` covers both People and Organizations.'
          example: lead
          required: true
          schema:
            type: string
            description: 'One of: lead, contact, deal, project. `contact` covers both People and Organizations.'
            example: lead
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
            example: 25
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      name: New
                      slug: lead-new
                      type: lead
                      color: '4299E1'
                      order: 1
                      is_locked: true
                    -
                      id: 2
                      name: Attempted
                      slug: lead-attempted
                      type: lead
                      color: ECC94B
                      order: 2
                      is_locked: false
                    -
                      id: 3
                      name: Contacted
                      slug: lead-contacted
                      type: lead
                      color: ED8936
                      order: 3
                      is_locked: false
                    -
                      id: 4
                      name: Qualified
                      slug: lead-qualified
                      type: lead
                      color: 48BB78
                      order: 4
                      is_locked: true
                    -
                      id: 5
                      name: Unqualified
                      slug: lead-unqualified
                      type: lead
                      color: F56565
                      order: 5
                      is_locked: true
                    -
                      id: 6
                      name: Converted
                      slug: lead-converted
                      type: lead
                      color: 38B2AC
                      order: 6
                      is_locked: true
                    -
                      id: 7
                      name: Archived
                      slug: lead-archived
                      type: lead
                      color: A0AEC0
                      order: 7
                      is_locked: true
                  links:
                    first: 'https://{your-subdomain}.saleskey.ai/api/v1/statuses?type=lead&per_page=25&page=1'
                    last: 'https://{your-subdomain}.saleskey.ai/api/v1/statuses?type=lead&per_page=25&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    per_page: 25
                    to: 7
                    total: 7
                    path: 'https://{your-subdomain}.saleskey.ai/api/v1/statuses'
                    links:
                      -
                        url: null
                        label: '« Previous'
                        page: null
                        active: false
                      -
                        url: 'https://{your-subdomain}.saleskey.ai/api/v1/statuses?type=lead&per_page=25&page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next »'
                        page: null
                        active: false
                properties:
                  data:
                    type: array
                    example:
                      - id: 1
                        name: New
                        slug: lead-new
                        type: lead
                        color: '4299E1'
                        order: 1
                        is_locked: true
                      - id: 2
                        name: Attempted
                        slug: lead-attempted
                        type: lead
                        color: ECC94B
                        order: 2
                        is_locked: false
                      - id: 3
                        name: Contacted
                        slug: lead-contacted
                        type: lead
                        color: ED8936
                        order: 3
                        is_locked: false
                      - id: 4
                        name: Qualified
                        slug: lead-qualified
                        type: lead
                        color: 48BB78
                        order: 4
                        is_locked: true
                      - id: 5
                        name: Unqualified
                        slug: lead-unqualified
                        type: lead
                        color: F56565
                        order: 5
                        is_locked: true
                      - id: 6
                        name: Converted
                        slug: lead-converted
                        type: lead
                        color: 38B2AC
                        order: 6
                        is_locked: true
                      - id: 7
                        name: Archived
                        slug: lead-archived
                        type: lead
                        color: A0AEC0
                        order: 7
                        is_locked: true
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: New
                        slug:
                          type: string
                          example: lead-new
                        type:
                          type: string
                          example: lead
                        color:
                          type: string
                          example: '4299E1'
                        order:
                          type: integer
                          example: 1
                        is_locked:
                          type: boolean
                          example: true
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/statuses?type=lead&per_page=25&page=1'
                      last:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/statuses?type=lead&per_page=25&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 25
                      to:
                        type: integer
                        example: 7
                      total:
                        type: integer
                        example: 7
                      path:
                        type: string
                        example: 'https://{your-subdomain}.saleskey.ai/api/v1/statuses'
                      links:
                        type: array
                        example:
                          - url: null
                            label: '« Previous'
                            page: null
                            active: false
                          - url: 'https://{your-subdomain}.saleskey.ai/api/v1/statuses?type=lead&per_page=25&page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next »'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '« Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'statuses'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'statuses'."
        422:
          description: 'Missing or invalid type'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      type:
                        - 'The selected type is invalid.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          type:
                            type: array
                            example:
                              - 'The selected type is invalid.'
                            items:
                              type: string
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - Statuses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: ''
                  example: lead
                  enum:
                    - lead
                    - contact
                    - deal
                    - project
              required:
                - type
  '/api/v1/statuses/{id}':
    get:
      summary: 'Retrieve a status'
      operationId: retrieveAStatus
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 1
                    name: New
                    slug: lead-new
                    type: lead
                    color: '4299E1'
                    order: 1
                    is_locked: true
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: New
                      slug:
                        type: string
                        example: lead-new
                      type:
                        type: string
                        example: lead
                      color:
                        type: string
                        example: '4299E1'
                      order:
                        type: integer
                        example: 1
                      is_locked:
                        type: boolean
                        example: true
        404:
          description: 'Status not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Status not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Status not found.'
      tags:
        - Statuses
    parameters:
      -
        in: path
        name: id
        description: 'The status ID.'
        example: 1
        required: true
        schema:
          type: integer
  /api/v1/labels:
    get:
      summary: 'List labels'
      operationId: listLabels
      description: "Returns the labels defined for a single type, ordered the same way\nthey appear in the Settings UI. Not paginated - label counts per type\nare typically small."
      parameters:
        -
          in: query
          name: type
          description: 'One of: lead, deal, project.'
          example: lead
          required: true
          schema:
            type: string
            description: 'One of: lead, deal, project.'
            example: lead
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      name: Hot
                      slug: lead-hot
                      type: lead
                      color: F56565
                      order: 1
                    -
                      id: 2
                      name: Warm
                      slug: lead-warm
                      type: lead
                      color: ED8936
                      order: 2
                    -
                      id: 3
                      name: Cold
                      slug: lead-cold
                      type: lead
                      color: '4299E1'
                      order: 3
                properties:
                  data:
                    type: array
                    example:
                      - id: 1
                        name: Hot
                        slug: lead-hot
                        type: lead
                        color: F56565
                        order: 1
                      - id: 2
                        name: Warm
                        slug: lead-warm
                        type: lead
                        color: ED8936
                        order: 2
                      - id: 3
                        name: Cold
                        slug: lead-cold
                        type: lead
                        color: '4299E1'
                        order: 3
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Hot
                        slug:
                          type: string
                          example: lead-hot
                        type:
                          type: string
                          example: lead
                        color:
                          type: string
                          example: F56565
                        order:
                          type: integer
                          example: 1
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'labels'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'labels'."
        422:
          description: 'Missing or invalid type'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      type:
                        - 'The selected type is invalid.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          type:
                            type: array
                            example:
                              - 'The selected type is invalid.'
                            items:
                              type: string
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - Labels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: ''
                  example: lead
                  enum:
                    - lead
                    - deal
                    - project
              required:
                - type
  '/api/v1/labels/{id}':
    get:
      summary: 'Retrieve a label'
      operationId: retrieveALabel
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 1
                    name: Hot
                    slug: lead-hot
                    type: lead
                    color: F56565
                    order: 1
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: Hot
                      slug:
                        type: string
                        example: lead-hot
                      type:
                        type: string
                        example: lead
                      color:
                        type: string
                        example: F56565
                      order:
                        type: integer
                        example: 1
        404:
          description: 'Label not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Label not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Label not found.'
      tags:
        - Labels
    parameters:
      -
        in: path
        name: id
        description: 'The label ID.'
        example: 1
        required: true
        schema:
          type: integer
  /api/v1/source-channels:
    get:
      summary: 'List source channels'
      operationId: listSourceChannels
      description: "Returns every source channel, ordered the same way they appear in the\nSettings UI. Not paginated - source channel counts are typically small."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      name: Website
                      order: 1
                    -
                      id: 2
                      name: Referral
                      order: 4
                properties:
                  data:
                    type: array
                    example:
                      - id: 1
                        name: Website
                        order: 1
                      - id: 2
                        name: Referral
                        order: 4
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Website
                        order:
                          type: integer
                          example: 1
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'source_channels'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'source_channels'."
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - 'Source Channels'
  '/api/v1/source-channels/{id}':
    get:
      summary: 'Retrieve a source channel'
      operationId: retrieveASourceChannel
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 1
                    name: Website
                    order: 1
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: Website
                      order:
                        type: integer
                        example: 1
        404:
          description: 'Source channel not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Source channel not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Source channel not found.'
      tags:
        - 'Source Channels'
    parameters:
      -
        in: path
        name: id
        description: 'The source channel ID.'
        example: 1
        required: true
        schema:
          type: integer
  /api/v1/pipelines:
    get:
      summary: 'List pipelines'
      operationId: listPipelines
      description: "Returns every active pipeline with its stages. Not paginated - pipeline\ncounts are typically small."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      name: 'Deal Flow'
                      is_active: true
                      has_probabilities: true
                      stages:
                        -
                          id: 1
                          name: Qualified
                          color: EF4444
                          order: 1
                          probability: '10.00'
                        -
                          id: 2
                          name: 'Contact Made'
                          color: F59E0B
                          order: 2
                          probability: '30.00'
                        -
                          id: 3
                          name: 'Demo Scheduled'
                          color: EAB308
                          order: 3
                          probability: '50.00'
                        -
                          id: 4
                          name: 'Proposal Made'
                          color: 3B82F6
                          order: 4
                          probability: '75.00'
                        -
                          id: 5
                          name: 'Negotiation Started'
                          color: 10B981
                          order: 5
                          probability: '100.00'
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1
                        name: 'Deal Flow'
                        is_active: true
                        has_probabilities: true
                        stages:
                          - id: 1
                            name: Qualified
                            color: EF4444
                            order: 1
                            probability: '10.00'
                          - id: 2
                            name: 'Contact Made'
                            color: F59E0B
                            order: 2
                            probability: '30.00'
                          - id: 3
                            name: 'Demo Scheduled'
                            color: EAB308
                            order: 3
                            probability: '50.00'
                          - id: 4
                            name: 'Proposal Made'
                            color: 3B82F6
                            order: 4
                            probability: '75.00'
                          - id: 5
                            name: 'Negotiation Started'
                            color: 10B981
                            order: 5
                            probability: '100.00'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: 'Deal Flow'
                        is_active:
                          type: boolean
                          example: true
                        has_probabilities:
                          type: boolean
                          example: true
                        stages:
                          type: array
                          example:
                            - id: 1
                              name: Qualified
                              color: EF4444
                              order: 1
                              probability: '10.00'
                            - id: 2
                              name: 'Contact Made'
                              color: F59E0B
                              order: 2
                              probability: '30.00'
                            - id: 3
                              name: 'Demo Scheduled'
                              color: EAB308
                              order: 3
                              probability: '50.00'
                            - id: 4
                              name: 'Proposal Made'
                              color: 3B82F6
                              order: 4
                              probability: '75.00'
                            - id: 5
                              name: 'Negotiation Started'
                              color: 10B981
                              order: 5
                              probability: '100.00'
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              name:
                                type: string
                                example: Qualified
                              color:
                                type: string
                                example: EF4444
                              order:
                                type: integer
                                example: 1
                              probability:
                                type: string
                                example: '10.00'
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'pipelines'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'pipelines'."
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - Pipelines
  '/api/v1/pipelines/{id}':
    get:
      summary: 'Retrieve a pipeline'
      operationId: retrieveAPipeline
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 1
                    name: 'Deal Flow'
                    is_active: true
                    has_probabilities: true
                    stages:
                      -
                        id: 1
                        name: Qualified
                        color: EF4444
                        order: 1
                        probability: '10.00'
                      -
                        id: 2
                        name: 'Contact Made'
                        color: F59E0B
                        order: 2
                        probability: '30.00'
                      -
                        id: 3
                        name: 'Demo Scheduled'
                        color: EAB308
                        order: 3
                        probability: '50.00'
                      -
                        id: 4
                        name: 'Proposal Made'
                        color: 3B82F6
                        order: 4
                        probability: '75.00'
                      -
                        id: 5
                        name: 'Negotiation Started'
                        color: 10B981
                        order: 5
                        probability: '100.00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: 'Deal Flow'
                      is_active:
                        type: boolean
                        example: true
                      has_probabilities:
                        type: boolean
                        example: true
                      stages:
                        type: array
                        example:
                          - id: 1
                            name: Qualified
                            color: EF4444
                            order: 1
                            probability: '10.00'
                          - id: 2
                            name: 'Contact Made'
                            color: F59E0B
                            order: 2
                            probability: '30.00'
                          - id: 3
                            name: 'Demo Scheduled'
                            color: EAB308
                            order: 3
                            probability: '50.00'
                          - id: 4
                            name: 'Proposal Made'
                            color: 3B82F6
                            order: 4
                            probability: '75.00'
                          - id: 5
                            name: 'Negotiation Started'
                            color: 10B981
                            order: 5
                            probability: '100.00'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Qualified
                            color:
                              type: string
                              example: EF4444
                            order:
                              type: integer
                              example: 1
                            probability:
                              type: string
                              example: '10.00'
        404:
          description: 'Pipeline not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Pipeline not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Pipeline not found.'
      tags:
        - Pipelines
    parameters:
      -
        in: path
        name: id
        description: 'The pipeline ID.'
        example: 1
        required: true
        schema:
          type: integer
  /api/v1/users:
    get:
      summary: 'List users'
      operationId: listUsers
      description: 'Returns a paginated list of active (non-deleted) users.'
      parameters:
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Results per page (default 25, max 200 - values above 200 are clamped).'
            example: 25
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      name: 'Jane Owner'
                      email: jane@acme.test
                      status: active
                      roles:
                        - 'Account Owner'
                      created_at: '2026-07-23T10:00:00+00:00'
                      updated_at: '2026-07-23T10:00:00+00:00'
                  links:
                    first: ...
                    last: ...
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    per_page: 25
                    total: 1
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1
                        name: 'Jane Owner'
                        email: jane@acme.test
                        status: active
                        roles:
                          - 'Account Owner'
                        created_at: '2026-07-23T10:00:00+00:00'
                        updated_at: '2026-07-23T10:00:00+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: 'Jane Owner'
                        email:
                          type: string
                          example: jane@acme.test
                        status:
                          type: string
                          example: active
                        roles:
                          type: array
                          example:
                            - 'Account Owner'
                          items:
                            type: string
                        created_at:
                          type: string
                          example: '2026-07-23T10:00:00+00:00'
                        updated_at:
                          type: string
                          example: '2026-07-23T10:00:00+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: ...
                      last:
                        type: string
                        example: ...
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 25
                      total:
                        type: integer
                        example: 1
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'users'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'users'."
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - Users
  '/api/v1/users/{id}':
    get:
      summary: 'Retrieve a user'
      operationId: retrieveAUser
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 1
                    name: 'Jane Owner'
                    email: jane@acme.test
                    status: active
                    roles:
                      - 'Account Owner'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: 'Jane Owner'
                      email:
                        type: string
                        example: jane@acme.test
                      status:
                        type: string
                        example: active
                      roles:
                        type: array
                        example:
                          - 'Account Owner'
                        items:
                          type: string
        404:
          description: 'User not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'User not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'User not found.'
      tags:
        - Users
    parameters:
      -
        in: path
        name: id
        description: 'The user ID.'
        example: 1
        required: true
        schema:
          type: integer
  /api/v1/fields:
    get:
      summary: 'List fields'
      operationId: listFields
      description: "Returns every visible built-in and custom field for a single entity\ntype, in the same order they appear in the Settings UI, including\nresolved options for select/multiselect fields."
      parameters:
        -
          in: query
          name: type
          description: 'One of: lead, deal, person, organization.'
          example: lead
          required: true
          schema:
            type: string
            description: 'One of: lead, deal, person, organization.'
            example: lead
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 29
                      slug: lead_title
                      name: Title
                      type: input
                      relation_type: lead
                      is_default: true
                      options: null
                      order: 1
                    -
                      id: 32
                      slug: lead_currency
                      name: Currency
                      type: select_currency
                      relation_type: lead
                      is_default: true
                      options: null
                      options_source: currencies
                      order: 4
                    -
                      id: 33
                      slug: lead_value
                      name: Value
                      type: input_money
                      relation_type: lead
                      is_default: true
                      options: null
                      order: 5
                    -
                      id: 36
                      slug: lead_expected_close_date
                      name: 'Expected Close Date'
                      type: date
                      relation_type: lead
                      is_default: true
                      options: null
                      order: 8
                    -
                      id: 37
                      slug: lead_person_id
                      name: Person
                      type: create_or_select_person
                      relation_type: lead
                      is_default: true
                      options: []
                      order: 9
                    -
                      id: 38
                      slug: lead_organization_id
                      name: Organization
                      type: create_or_select_organization
                      relation_type: lead
                      is_default: true
                      options: []
                      order: 10
                    -
                      id: 39
                      slug: lead_status_id
                      name: Status
                      type: select_status
                      relation_type: lead
                      is_default: true
                      options:
                        -
                          value: 1
                          label: New
                        -
                          value: 2
                          label: Attempted
                        -
                          value: 3
                          label: Contacted
                        -
                          value: 4
                          label: Qualified
                        -
                          value: 5
                          label: Unqualified
                        -
                          value: 6
                          label: Converted
                        -
                          value: 7
                          label: Archived
                      order: 11
                    -
                      id: 40
                      slug: lead_labels
                      name: Labels
                      type: multiselect_labels
                      relation_type: lead
                      is_default: true
                      options:
                        -
                          value: 1
                          label: Hot
                        -
                          value: 2
                          label: Warm
                        -
                          value: 3
                          label: Cold
                      order: 12
                    -
                      id: 41
                      slug: lead_source_channel_id
                      name: 'Source Channel'
                      type: select_source_channel
                      relation_type: lead
                      is_default: true
                      options:
                        -
                          value: 1
                          label: Website
                        -
                          value: 2
                          label: 'Social Media'
                        -
                          value: 3
                          label: 'Email Campaign'
                        -
                          value: 4
                          label: Referral
                        -
                          value: 5
                          label: Event
                        -
                          value: 6
                          label: Prospector
                      order: 13
                    -
                      id: 43
                      slug: lead_owner_id
                      name: Owner
                      type: select_user
                      relation_type: lead
                      is_default: true
                      options:
                        -
                          value: 1
                          label: 'Jane Owner'
                      order: 15
                    -
                      id: 44
                      slug: lead_assignees
                      name: Assignees
                      type: multiselect_users
                      relation_type: lead
                      is_default: true
                      options:
                        -
                          value: 1
                          label: 'Jane Owner'
                      order: 16
                    -
                      id: 542
                      slug: lead_region
                      name: Region
                      type: select
                      relation_type: lead
                      is_default: false
                      options:
                        - Asia
                        - Europe
                        - 'North America'
                        - 'South America'
                        - Africa
                        - Australia
                      order: 21
                properties:
                  data:
                    type: array
                    example:
                      - id: 29
                        slug: lead_title
                        name: Title
                        type: input
                        relation_type: lead
                        is_default: true
                        options: null
                        order: 1
                      - id: 32
                        slug: lead_currency
                        name: Currency
                        type: select_currency
                        relation_type: lead
                        is_default: true
                        options: null
                        options_source: currencies
                        order: 4
                      - id: 33
                        slug: lead_value
                        name: Value
                        type: input_money
                        relation_type: lead
                        is_default: true
                        options: null
                        order: 5
                      - id: 36
                        slug: lead_expected_close_date
                        name: 'Expected Close Date'
                        type: date
                        relation_type: lead
                        is_default: true
                        options: null
                        order: 8
                      -
                        id: 37
                        slug: lead_person_id
                        name: Person
                        type: create_or_select_person
                        relation_type: lead
                        is_default: true
                        options: []
                        order: 9
                      -
                        id: 38
                        slug: lead_organization_id
                        name: Organization
                        type: create_or_select_organization
                        relation_type: lead
                        is_default: true
                        options: []
                        order: 10
                      -
                        id: 39
                        slug: lead_status_id
                        name: Status
                        type: select_status
                        relation_type: lead
                        is_default: true
                        options:
                          - value: 1
                            label: New
                          - value: 2
                            label: Attempted
                          - value: 3
                            label: Contacted
                          - value: 4
                            label: Qualified
                          - value: 5
                            label: Unqualified
                          - value: 6
                            label: Converted
                          - value: 7
                            label: Archived
                        order: 11
                      -
                        id: 40
                        slug: lead_labels
                        name: Labels
                        type: multiselect_labels
                        relation_type: lead
                        is_default: true
                        options:
                          - value: 1
                            label: Hot
                          - value: 2
                            label: Warm
                          - value: 3
                            label: Cold
                        order: 12
                      -
                        id: 41
                        slug: lead_source_channel_id
                        name: 'Source Channel'
                        type: select_source_channel
                        relation_type: lead
                        is_default: true
                        options:
                          - value: 1
                            label: Website
                          - value: 2
                            label: 'Social Media'
                          - value: 3
                            label: 'Email Campaign'
                          - value: 4
                            label: Referral
                          - value: 5
                            label: Event
                          - value: 6
                            label: Prospector
                        order: 13
                      -
                        id: 43
                        slug: lead_owner_id
                        name: Owner
                        type: select_user
                        relation_type: lead
                        is_default: true
                        options:
                          - value: 1
                            label: 'Jane Owner'
                        order: 15
                      -
                        id: 44
                        slug: lead_assignees
                        name: Assignees
                        type: multiselect_users
                        relation_type: lead
                        is_default: true
                        options:
                          - value: 1
                            label: 'Jane Owner'
                        order: 16
                      -
                        id: 542
                        slug: lead_region
                        name: Region
                        type: select
                        relation_type: lead
                        is_default: false
                        options:
                          - Asia
                          - Europe
                          - 'North America'
                          - 'South America'
                          - Africa
                          - Australia
                        order: 21
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 29
                        slug:
                          type: string
                          example: lead_title
                        name:
                          type: string
                          example: Title
                        type:
                          type: string
                          example: input
                        relation_type:
                          type: string
                          example: lead
                        is_default:
                          type: boolean
                          example: true
                        options:
                          type: string
                          example: null
                          nullable: true
                        order:
                          type: integer
                          example: 1
        401:
          description: 'Missing or invalid key'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_api_key
                    message: 'A valid API key is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_api_key
                      message:
                        type: string
                        example: 'A valid API key is required.'
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not on Professional plan'
                    type: object
                    example:
                      error:
                        code: plan_upgrade_required
                        message: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: plan_upgrade_required
                          message:
                            type: string
                            example: 'The REST API is only available on the Professional plan. Please upgrade to continue.'
                  -
                    description: 'Key lacks permission'
                    type: object
                    example:
                      error:
                        code: insufficient_permissions
                        message: "This API key does not have 'read' permission for 'fields'."
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: insufficient_permissions
                          message:
                            type: string
                            example: "This API key does not have 'read' permission for 'fields'."
        422:
          description: 'Missing or invalid type'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation_failed
                    message: 'The given data was invalid.'
                    details:
                      type:
                        - 'The selected type is invalid.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_failed
                      message:
                        type: string
                        example: 'The given data was invalid.'
                      details:
                        type: object
                        properties:
                          type:
                            type: array
                            example:
                              - 'The selected type is invalid.'
                            items:
                              type: string
        429:
          description: 'Rate limited'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: rate_limit_exceeded
                    message: 'Too many requests. Please retry later.'
                    retry_after: 42
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: rate_limit_exceeded
                      message:
                        type: string
                        example: 'Too many requests. Please retry later.'
                      retry_after:
                        type: integer
                        example: 42
      tags:
        - Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: ''
                  example: person
                  enum:
                    - lead
                    - deal
                    - person
                    - organization
              required:
                - type
  '/api/v1/fields/{id}':
    get:
      summary: 'Retrieve a field'
      operationId: retrieveAField
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 39
                    slug: lead_status_id
                    name: Status
                    type: select_status
                    relation_type: lead
                    is_default: true
                    options:
                      -
                        value: 1
                        label: New
                      -
                        value: 2
                        label: Attempted
                      -
                        value: 3
                        label: Contacted
                      -
                        value: 4
                        label: Qualified
                      -
                        value: 5
                        label: Unqualified
                      -
                        value: 6
                        label: Converted
                      -
                        value: 7
                        label: Archived
                    order: 11
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 39
                      slug:
                        type: string
                        example: lead_status_id
                      name:
                        type: string
                        example: Status
                      type:
                        type: string
                        example: select_status
                      relation_type:
                        type: string
                        example: lead
                      is_default:
                        type: boolean
                        example: true
                      options:
                        type: array
                        example:
                          - value: 1
                            label: New
                          - value: 2
                            label: Attempted
                          - value: 3
                            label: Contacted
                          - value: 4
                            label: Qualified
                          - value: 5
                            label: Unqualified
                          - value: 6
                            label: Converted
                          - value: 7
                            label: Archived
                        items:
                          type: object
                          properties:
                            value:
                              type: integer
                              example: 1
                            label:
                              type: string
                              example: New
                      order:
                        type: integer
                        example: 11
        404:
          description: 'Field not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Field not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Field not found.'
      tags:
        - Fields
    parameters:
      -
        in: path
        name: id
        description: 'The field ID.'
        example: 11
        required: true
        schema:
          type: integer
