Instantly Lead Label API

openapi: 3.2.0
info:
  title: Explorer Lead Label API
  description: The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the `ApiKeyAuth_token` blue text.
  version: 2.0.0
servers:
- url: https://api.instantly.ai
  description: Instantly API Server
security:
- ApiKeyAuth: []
tags:
- name: LeadLabel
  description: A custom label for categorizing and managing leads
  x-group: Lead Label
paths:
  /api/v2/lead-labels:
    post:
      operationId: createLeadLabel
      summary: Create lead label
      tags:
      - LeadLabel
      description: 'Requires one of the following scopes: `lead-labels:create`, `lead-labels:all`, `all:create`, `all:all`'
      requestBody:
        content:
          application/json:
            schema:
              title: CreateLead Label
              description: The Lead Label to create
              type: object
              properties:
                label:
                  type: string
                  description: Display label for the custom lead label
                  example: Hot Lead
                interest_status_label:
                  type: string
                  description: Interest status label associated with this label
                  enum:
                  - positive
                  - negative
                  - neutral
                  x-enumDescriptions:
                    positive: Positive
                    negative: Negative
                    neutral: Neutral
                  example: positive
                description:
                  type:
                  - string
                  - 'null'
                  description: Detailed description of the custom lead label purpose
                  example: Used for marking high-priority leads
                use_with_ai:
                  type:
                  - boolean
                  - 'null'
                  description: Whether this label should be used with AI features
                  example: false
              required:
              - label
              - interest_status_label
              additionalProperties: false
        required: true
        description: The Lead Label to create
      responses:
        '200':
          description: The Lead Label
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadLabel'
        '400':
          description: Invalid request body (e.g. missing required fields, or invalid field values)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 400
                    examples:
                    - 400
                    example: 400
                  error:
                    type: string
                    enum:
                    - Bad Request
                    examples:
                    - Bad Request
                    example: Bad Request
                  message:
                    type: string
                    examples:
                    - body must have required property 'name'
                    example: body must have required property 'name'
                required:
                - statusCode
                - error
                - message
        '401':
          description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 401
                    examples:
                    - 401
                    example: 401
                  error:
                    type: string
                    enum:
                    - Unauthorized
                    examples:
                    - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                    - Missing Authorization header
                    example: Missing Authorization header
                required:
                - statusCode
                - error
                - message
        '402':
          description: This request cannot be fulfilled because the workspace does not have an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 402
                    examples:
                    - 402
                    example: 402
                  error:
                    type: string
                    enum:
                    - Payment Required
                    examples:
                    - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    examples:
                    - Workspace does not have an active paid plan
                    example: Workspace does not have an active paid plan
                required:
                - statusCode
                - error
                - message
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 404
                    examples:
                    - 404
                    example: 404
                  error:
                    type: string
                    enum:
                    - Not Found
                    examples:
                    - Not Found
                    example: Not Found
                  message:
                    type: string
                    examples:
                    - Resource not found
                    example: Resource not found
                required:
                - statusCode
                - error
                - message
        '429':
          description: You have exceeded the rate limit. Please check the rate limit docs for more information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 429
                    examples:
                    - 429
                    example: 429
                  error:
                    type: string
                    enum:
                    - Too Many Requests
                    examples:
                    - Too Many Requests
                    example: Too Many Requests
                  message:
                    type: string
                    examples:
                    - Rate limit exceeded
                    example: Rate limit exceeded
                required:
                - statusCode
                - error
                - message
    get:
      operationId: listLeadLabel
      summary: List lead label
      tags:
      - LeadLabel
      description: 'Requires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`'
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          example: 10
        example: 10
        in: query
        name: limit
        required: false
        description: The number of items to return
      - schema:
          type: string
          example: '2025-03-07T00:00:00.000Z'
        example: '2025-03-07T00:00:00.000Z'
        in: query
        name: starting_after
        required: false
        description: The starting after timestamp to filter lead labels by.
      - schema:
          type: string
          example: Hot Lead
        example: Hot Lead
        in: query
        name: search
        required: false
        description: The search query to filter lead labels.
      - schema:
          type: string
          enum:
          - positive
          - neutral
          - negative
          example: positive
        example: positive
        in: query
        name: interest_status
        required: false
        description: The interest status to filter lead labels by.
      responses:
        '200':
          description: The list of Lead Label
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: The list of Lead Label
                    items:
                      $ref: '#/components/schemas/LeadLabel'
                  next_starting_after:
                    type: string
                    examples:
                    - 019ffad2-9c33-720b-b2c0-a2f792c0db40
                    - '2026-08-13T11:12:14.387Z'
                    description: The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API
                    example: 019ffad2-9c33-720b-b2c0-a2f792c0db40
                additionalProperties: false
                required:
                - items
        '401':
          description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 401
                    examples:
                    - 401
                    example: 401
                  error:
                    type: string
                    enum:
                    - Unauthorized
                    examples:
                    - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                    - Missing Authorization header
                    example: Missing Authorization header
                required:
                - statusCode
                - error
                - message
        '402':
          description: This request cannot be fulfilled because the workspace does not have an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 402
                    examples:
                    - 402
                    example: 402
                  error:
                    type: string
                    enum:
                    - Payment Required
                    examples:
                    - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    examples:
                    - Workspace does not have an active paid plan
                    example: Workspace does not have an active paid plan
                required:
                - statusCode
                - error
                - message
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 404
                    examples:
                    - 404
                    example: 404
                  error:
                    type: string
                    enum:
                    - Not Found
                    examples:
                    - Not Found
                    example: Not Found
                  message:
                    type: string
                    examples:
                    - Resource not found
                    example: Resource not found
                required:
                - statusCode
                - error
                - message
        '429':
          description: You have exceeded the rate limit. Please check the rate limit docs for more information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 429
                    examples:
                    - 429
                    example: 429
                  error:
                    type: string
                    enum:
                    - Too Many Requests
                    examples:
                    - Too Many Requests
                    example: Too Many Requests
                  message:
                    type: string
                    examples:
                    - Rate limit exceeded
                    example: Rate limit exceeded
                required:
                - statusCode
                - error
                - message
  /api/v2/lead-labels/{id}:
    get:
      operationId: getLeadLabel
      summary: Get lead label
      tags:
      - LeadLabel
      description: 'Requires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`'
      parameters:
      - schema:
          type: string
          format: uuid
          example: 019ffad2-9c34-7f68-8145-ec292e79cfac
        example: 019ffad2-9c34-7f68-8145-ec292e79cfac
        in: path
        name: id
        required: true
        description: The ID of the requested item
      responses:
        '200':
          description: The requested Lead Label
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadLabel'
        '401':
          description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 401
                    examples:
                    - 401
                    example: 401
                  error:
                    type: string
                    enum:
                    - Unauthorized
                    examples:
                    - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                    - Missing Authorization header
                    example: Missing Authorization header
                required:
                - statusCode
                - error
                - message
        '402':
          description: This request cannot be fulfilled because the workspace does not have an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 402
                    examples:
                    - 402
                    example: 402
                  error:
                    type: string
                    enum:
                    - Payment Required
                    examples:
                    - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    examples:
                    - Workspace does not have an active paid plan
                    example: Workspace does not have an active paid plan
                required:
                - statusCode
                - error
                - message
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 404
                    examples:
                    - 404
                    example: 404
                  error:
                    type: string
                    enum:
                    - Not Found
                    examples:
                    - Not Found
                    example: Not Found
                  message:
                    type: string
                    examples:
                    - Resource not found
                    example: Resource not found
                required:
                - statusCode
                - error
                - message
        '429':
          description: You have exceeded the rate limit. Please check the rate limit docs for more information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 429
                    examples:
                    - 429
                    example: 429
                  error:
                    type: string
                    enum:
                    - Too Many Requests
                    examples:
                    - Too Many Requests
                    example: Too Many Requests
                  message:
                    type: string
                    examples:
                    - Rate limit exceeded
                    example: Rate limit exceeded
                required:
                - statusCode
                - error
                - message
    patch:
      operationId: patchLeadLabel
      summary: Patch lead label
      tags:
      - LeadLabel
      description: 'Requires one of the following scopes: `lead-labels:update`, `lead-labels:all`, `all:update`, `all:all`'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: Display label for the custom lead label
                  example: Hot Lead
                interest_status_label:
                  type: string
                  description: Interest status label associated with this label
                  enum:
                  - positive
                  - negative
                  - neutral
                  x-enumDescriptions:
                    positive: Positive
                    negative: Negative
                    neutral: Neutral
                  example: positive
                description:
                  type:
                  - string
                  - 'null'
                  description: Detailed description of the custom lead label purpose
                  example: Used for marking high-priority leads
                use_with_ai:
                  type:
                  - boolean
                  - 'null'
                  description: Whether this label should be used with AI features
                  example: false
              required: []
              additionalProperties: false
              minProperties: 1
      parameters:
      - schema:
          type: string
          format: uuid
          example: 019ffad2-9c34-7f68-8145-ec2a406f5831
        example: 019ffad2-9c34-7f68-8145-ec2a406f5831
        in: path
        name: id
        required: true
        description: The ID of the item to update
      responses:
        '200':
          description: The updated Lead Label
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadLabel'
        '401':
          description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 401
                    examples:
                    - 401
                    example: 401
                  error:
                    type: string
                    enum:
                    - Unauthorized
                    examples:
                    - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                    - Missing Authorization header
                    example: Missing Authorization header
                required:
                - statusCode
                - error
                - message
        '402':
          description: This request cannot be fulfilled because the workspace does not have an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 402
                    examples:
                    - 402
                    example: 402
                  error:
                    type: string
                    enum:
                    - Payment Required
                    examples:
                    - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    examples:
                    - Workspace does not have an active paid plan
                    example: Workspace does not have an active paid plan
                required:
                - statusCode
                - error
                - message
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 404
                    examples:
                    - 404
                    example: 404
                  error:
                    type: string
                    enum:
                    - Not Found
                    examples:
                    - Not Found
                    example: Not Found
                  message:
                    type: string
                    examples:
                    - Resource not found
                    example: Resource not found
                required:
                - statusCode
                - error
                - message
        '429':
          description: You have exceeded the rate limit. Please check the rate limit docs for more information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 429
                    examples:
                    - 429
                    example: 429
                  error:
                    type: string
                    enum:
                    - Too Many Requests
                    examples:
                    - Too Many Requests
                    example: Too Many Requests
                  message:
                    type: string
                    examples:
                    - Rate limit exceeded
                    example: Rate limit exceeded
                required:
                - statusCode
                - error
                - message
    delete:
      operationId: deleteLeadLabel
      summary: Delete lead label
      tags:
      - LeadLabel
      description: 'Requires one of the following scopes: `lead-labels:delete`, `lead-labels:all`, `all:delete`, `all:all`'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                reassigned_status:
                  type: number
                  examples:
                  - 1
                  description: The interest status to reassign leads and emails to.
                  example: 1
      parameters:
      - schema:
          type: string
          format: uuid
          example: 019ffad2-9c34-7f68-8145-ec2b40927309
        example: 019ffad2-9c34-7f68-8145-ec2b40927309
        in: path
        name: id
        required: true
        description: The ID of the item to delete
      responses:
        '200':
          description: The deleted Lead Label
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadLabel'
        '401':
          description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 401
                    examples:
                    - 401
                    example: 401
                  error:
                    type: string
                    enum:
                    - Unauthorized
                    examples:
                    - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                    - Missing Authorization header
                    example: Missing Authorization header
                required:
                - statusCode
                - error
                - message
        '402':
          description: This request cannot be fulfilled because the workspace does not have an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 402
                    examples:
                    - 402
                    example: 402
                  error:
                    type: string
                    enum:
                    - Payment Required
                    examples:
                    - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    examples:
                    - Workspace does not have an active paid plan
                    example: Workspace does not have an active paid plan
                required:
                - statusCode
                - error
                - message
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 404
                    examples:
                    - 404
                    example: 404
                  error:
                    type: string
                    enum:
                    - Not Found
                    examples:
                    - Not Found
                    example: Not Found
                  message:
                    type: string
                    examples:
                    - Resource not found
                    example: Resource not found
                required:
                - statusCode
                - error
                - message
        '429':
          description: You have exceeded the rate limit. Please check the rate limit docs for more information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 429
                    examples:
                    - 429
                    example: 429
                  error:
                    type: string
                    enum:
                    - Too Many Requests
                    examples:
                    - Too Many Requests
                    example: Too Many Requests
                  message:
                    type: string
                    examples:
                    - Rate limit exceeded
                    example: Rate limit exceeded
                required:
                - statusCode
                - error
                - message
  /api/v2/lead-labels/ai-reply-label:
    post:
      operationId: testAiReplyLabelLeadLabels
      summary: Test AI reply label prediction
      tags:
      - LeadLabel
      description: 'Returns the AI-predicted lead label for a reply text. This simulates how AI auto-tagging would label an incoming reply for testing custom labels and descriptions. Rate limit: 500 requests per 30 days per workspace. This rate limit applies only to this testing endpoint; live reply processing does not use this limiter.



        Requires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reply_text:
                  type: string
                  description: The reply text to classify.
                  example: Thanks for reaching out. I am interested in learning more.
              required:
              - reply_text
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: The predicted lead label.
                    example: Hot Lead
                  custom_labels_considered:
                    type: array
                    items:
                      type: string
                      example: Hot Lead
                    description: AI-enabled custom labels considered during classification.
                    example:
                    - Hot Lead
                    - Needs Follow-up
        '401':
          description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 401
                    examples:
                    - 401
                    example: 401
                  error:
                    type: string
                    enum:
                    - Unauthorized
                    examples:
                    - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                    - Missing Authorization header
                    example: Missing Authorization header
                required:
                - statusCode
                - error
                - message
        '402':
          description: This request cannot be fulfilled because the workspace does not have an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 402
                    examples:
                    - 402
                    example: 402
                  error:
                    type: string
                    enum:
                    - Paymen

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instantly-ai/refs/heads/main/openapi/instantly-ai-leadlabel-api-openapi.yml