Leadping Lead Status Changes API

openapi: 3.2.0
info:
  title: Leadping Lead Status Changes API
  description: The Leadping API helps businesses capture and manage leads, automate follow-up, send SMS and MMS messages, place calls, track conversations, enforce contact suppression, and analyze communication workflows. Use this OpenAPI 3.1 contract to integrate lead sources, build organization tools, or generate a typed API client. Authenticate protected operations with a Leadping user access token or WorkOS organization API key. Lead intake operations also accept a Leadping source key.
  termsOfService: https://leadping.ai/docs/terms-of-service
  contact:
    name: Leadping Support
    url: https://leadping.ai/contact
    email: support@leadping.ai
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: v1
  summary: Lead management, messaging, calling, and automation API
servers:
- url: https://api.leadping.ai
  description: Production
tags:
- name: LeadStatusChanges
  description: Manages the auditable history of lead status transitions. Use these endpoints to change a lead's status, correct transition records, search status history, and export status activity for reporting.
paths:
  /leads/{leadId}/status:
    put:
      tags:
      - LeadStatusChanges
      summary: Set a lead's current status
      description: Sets the lead's current structured status and records the change for audit, automation, and reporting.
      operationId: LeadStatusChanges_SetCurrent
      parameters:
      - name: leadId
        in: path
        description: The lead identifier.
        required: true
        schema:
          type: string
      requestBody:
        description: The new status and related workflow data.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LeadStatusChangeRequest'
              description: Defines a lead status transition or correction, including its target status, effective time, source, and explanatory context.
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LeadStatusChangeRequest'
              description: Defines a lead status transition or correction, including its target status, effective time, source, and explanatory context.
        required: true
      responses:
        '200':
          description: The lead status was successfully updated and recorded.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LeadStatusChangeResponse'
                description: Describes an auditable lead status transition, including the previous and new status, source, actor, and effective time.
        '404':
          description: A related resource was not found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '400':
          description: The request was invalid or malformed.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '403':
          description: The authenticated user or organization does not have permission to perform this operation.
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '429':
          description: The API rate limit for this account or client has been exceeded.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                minimum: 0
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
      security:
      - Bearer: []
  /lead-status-changes/{id}:
    put:
      tags:
      - LeadStatusChanges
      summary: Update a lead status history entry
      description: Updates a lead status history entry and, when it is current, updates the lead's current status.
      operationId: LeadStatusChanges_Update
      parameters:
      - name: id
        in: path
        description: The ID of the lead status change.
        required: true
        schema:
          type: string
      requestBody:
        description: The lead status change request payload for the operation.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LeadStatusChangeRequest'
              description: Defines a lead status transition or correction, including its target status, effective time, source, and explanatory context.
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LeadStatusChangeRequest'
              description: Defines a lead status transition or correction, including its target status, effective time, source, and explanatory context.
        required: true
      responses:
        '200':
          description: Returns the lead status change response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LeadStatusChangeResponse'
                description: Describes an auditable lead status transition, including the previous and new status, source, actor, and effective time.
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '400':
          description: The request was invalid or failed validation.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '403':
          description: The authenticated user or organization does not have permission to perform this operation.
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '429':
          description: The API rate limit for this account or client has been exceeded.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                minimum: 0
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
      security:
      - Bearer: []
    get:
      tags:
      - LeadStatusChanges
      summary: Get a lead status history entry
      description: Returns one lead status change record so users can review a lead outcome, related notes, and follow-up context.
      operationId: LeadStatusChanges_Get
      parameters:
      - name: id
        in: path
        description: The ID of the lead status change to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The lead status change was successfully retrieved.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LeadStatusChangeResponse'
                description: Describes an auditable lead status transition, including the previous and new status, source, actor, and effective time.
        '404':
          description: The specified lead status change was not found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '403':
          description: The authenticated user or organization does not have permission to perform this operation.
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '429':
          description: The API rate limit for this account or client has been exceeded.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                minimum: 0
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
      security:
      - Bearer: []
    delete:
      tags:
      - LeadStatusChanges
      summary: Delete a lead status history entry
      description: Deletes a lead status change from a lead when the outcome record should no longer appear in event or reporting views.
      operationId: LeadStatusChanges_Delete
      parameters:
      - name: id
        in: path
        description: The ID of the lead status change to delete.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The lead status change was successfully deleted.
          content:
            application/json: {}
        '404':
          description: The specified lead status change was not found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '403':
          description: The authenticated user or organization does not have permission to perform this operation.
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '429':
          description: The API rate limit for this account or client has been exceeded.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                minimum: 0
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
      security:
      - Bearer: []
  /lead-status-changes/all/my:
    post:
      tags:
      - LeadStatusChanges
      summary: List current-organization lead status history
      description: Returns a filtered, paginated history of lead status changes for the current organization for workflow analysis, reporting, and audit review.
      operationId: LeadStatusChanges_GetAllForCurrentOrganization
      requestBody:
        description: Pagination, filtering, and sorting options for the lead status history.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RequestDataOptions'
              description: Defines cursor pagination, sorting, search, exact-match filters, and range filters for a structured API query.
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RequestDataOptions'
              description: Defines cursor pagination, sorting, search, exact-match filters, and range filters for a structured API query.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PagedResultOfLeadStatusChangeResponse'
                description: Returns one page of query results together with page-size, optional total-count, and opaque continuation-cursor metadata.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '403':
          description: The authenticated user or organization does not have permission to perform this operation.
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '429':
          description: The API rate limit for this account or client has been exceeded.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                minimum: 0
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
      security:
      - Bearer: []
  /leads/{leadId}/status-history:
    get:
      tags:
      - LeadStatusChanges
      summary: List a lead's status history
      description: Lists lead status change outcome history for one lead, including prior outcomes, notes, follow-up context, timestamps, and actor details used for audit review.
      operationId: LeadStatusChanges_GetByLeadId
      parameters:
      - name: leadId
        in: path
        description: The ID of the lead to get lead status changes for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The lead status history was successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/LeadStatusChangeResponse'
                  description: Describes an auditable lead status transition, including the previous and new status, source, actor, and effective time.
        '404':
          description: The specified lead was not found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '403':
          description: The authenticated user or organization does not have permission to perform this operation.
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '429':
          description: The API rate limit for this account or client has been exceeded.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                minimum: 0
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
      security:
      - Bearer: []
  /leads/{leadId}/status-history/export:
    get:
      tags:
      - LeadStatusChanges
      summary: Export a lead's status history
      description: Exports lead status change data for one lead, packaging outcome history for reporting, audit review, or handoff workflows.
      operationId: LeadStatusChanges_ExportByLeadId
      parameters:
      - name: leadId
        in: path
        description: The lead identifier.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the lead status change export response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LeadStatusChangeExportResponse'
                description: Describes lead status change export data returned by Leadping.
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '403':
          description: The authenticated user or organization does not have permission to perform this operation.
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '429':
          description: The API rate limit for this account or client has been exceeded.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                minimum: 0
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
      security:
      - Bearer: []
components:
  schemas:
    LeadStatusChangeExportRow:
      type: object
      properties:
        leadId:
          type:
          - 'null'
          - string
          description: The lead ID associated with this lead status change export row.
        leadStatusChangeId:
          type:
          - 'null'
          - string
          description: The lead status change ID associated with this lead status change export row.
        type:
          type:
          - 'null'
          - string
          description: Category of status change represented by this exported row.
        outcome:
          type:
          - 'null'
          - string
          description: Result of the interaction or workflow step represented by this exported row.
        category:
          enum:
          - Open
          - Qualified
          - Converted
          - Lost
          - Invalid
          - Duplicate
          type:
          - 'null'
          - string
          description: Controlled lead status change categories used for reporting, automation, and analytics.
        oldLeadStatusChangeId:
          type:
          - 'null'
          - string
          description: Unique identifier of the old lead status change associated with this Leadping lead status change export row.
        oldLeadStatusChangeType:
          type:
          - 'null'
          - string
          description: Old lead status change type classification for this Leadping lead status change export row.
        oldLeadStatusChangeOutcome:
          type:
          - 'null'
          - string
          description: Old lead status change outcome associated with this Leadping lead status change export row.
        newLeadStatusChangeId:
          type:
          - 'null'
          - string
          description: Unique identifier of the new lead status change associated with this Leadping lead status change export row.
        changeSource:
          enum:
          - User
          - AI
          - Automation
          - System
          - API
          type:
          - 'null'
          - string
          description: Known sources that can change a lead's current lead status change.
        changedByUserId:
          type:
          - 'null'
          - string
          description: Unique identifier of the Leadping user who made the change.
        changedByAutomationId:
          type:
          - 'null'
          - string
          description: Unique identifier of the automation that changed the lead status change, when applicable.
        changedAt:
          type:
          - 'null'
          - string
          description: Date and time when the lead status change change occurred.
          format: date-time
        reason:
          type:
          - 'null'
          - string
          description: Human-readable explanation for the current lead status change export row outcome.
        followUpStatus:
          type:
          - 'null'
          - string
          description: The current follow up status for this lead status change export row.
        callbackAt:
          type:
          - 'null'
          - string
          description: UTC timestamp for callback at on this lead status change export row.
          format: date-time
        taskDueAt:
          type:
          - 'null'
          - string
          description: UTC timestamp for task due at on this lead status change export row.
          format: date-time
        appointmentStartAt:
          type:
          - 'null'
          - string
          description: UTC timestamp for appointment start at on this lead status change export row.
          format: date-time
        appointmentEndAt:
          type:
          - 'null'
          - string
          description: UTC timestamp for appointment end at on this lead status change export row.
          format: date-time
        assignedToUserId:
          type:
          - 'null'
          - string
          description: The assigned to user ID associated with this lead status change export row.
        sourceId:
          type:
          - 'null'
          - string
          description: The source ID associated with this lead status change export row.
        relatedCallEventId:
          type:
          - 'null'
          - string
          description: The related call event ID associated with this lead status change export row.
        isMissedCallFollowUp:
          type: boolean
          description: Whether this lead status change export row is missed call follow up.
        notes:
          type:
          - 'null'
          - string
          description: The operator or customer notes recorded for this lead status change export row.
        createdAt:
          type: string
          description: UTC timestamp for created at on this lead status change export row.
          format: date-time
        updatedAt:
          type: string
          description: UTC timestamp for updated at on this lead status change export row.
          format: date-time
      description: Describes lead status change export row data returned by Leadping.
    LeadStatusChangeResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique Leadping identifier for this lead status change.
        leadId:
          type: string
          description: The lead ID associated with this lead status change.
        leadName:
          type:
          - 'null'
          - string
          description: The display name of the lead associated with this lead status change.
        type:
          type: string
          description: Category of status change recorded for the lead.
        outcome:
          type: string
          description: Result of the interaction or workflow step that caused the status change.
        category:
          enum:
          - Open
          - Qualified
          - Converted
          - Lost
          - Invalid
          - Duplicate
          type:
          - 'null'
          - string
          description: Controlled lead status change categories used for reporting, automation, and analytics.
        oldLeadStatusChangeId:
          type:
          - 'null'
          - string
          description: Unique identifier of the old lead status change associated with this Leadping lead status change.
        oldLeadStatusChangeType:
          type:
          - 'null'
          - string
          description: Old lead status change type classification for this Leadping lead status change.
        oldLeadStatusChangeOutcome:
          type:
          - 'null'
          - string
          description: Old lead status change outcome associated with this Leadping lead status change.
        newLeadStatusChangeId:
          type:
          - 'null'
          - string
          description: Unique identifier of the new lead status change associated with this Leadping lead status change.
        notes:
          type: string
          description: The operator or customer notes recorded for this lead status change.
        reason:
          type:
          - 'null'
          - string
          description: The reason this lead status change was changed.
        changedByUserId:
          type:
          - 'null'
          - string
          description: Unique identifier of the Leadping user who made the change.
        changedByAutomationId:
          type:
          - 'null'
          - string
          description: Unique identifier of the automation that changed the lead status change, when applicable.
        changedAt:
          type:
          - 'null'
          - string
          description: Date and time when the lead status change change occurred.
          format: date-time
        changeSource:
          enum:
          - User
          - AI
          - Automation
          - System
          - API
          type:
          - 'null'
          - string
          description: Known sources that can change a lead's current lead status change.
        timestamp:
          type: string
          description: UTC timestamp for timestamp on this lead status change.
          format: date-time
        createdAt:
          type: string
          description: UTC timestamp for created at on this lead status change.
          format: date-time
        updatedAt:
          type: string
          description: UTC timestamp for updated at on this lead status change.
          format: date-time
        followUpStatus:
          type:
          - 'null'
          - string
          description: The current follow up status for this lead status change.
        callbackAt:
          type:
          - 'null'
          - string
          description: UTC timestamp for callback at on this lead status change.
          format: date-time
        taskDueAt:
          type:
          - 'null'
          - string
          description: UTC timestamp for task due at on this lead status change.
          format: date-time
        appointmentStartAt:
          type:
          - 'null'
          - string
          description: UTC timestamp for appointment start at on this lead status change.
          format: date-time
        appointmentEndAt:
          type:
          - 'null'
          - string
          description: UTC timestamp for appointment end at on this lead status change.
          format: date-time
        appointmentNotes:
          type:
          - 'null'
          - string
          description: Additional scheduling or preparation notes for the related appointment.
        assignedToUserId:
          type:
          - 'null'
          - string
          description: The assigned to user ID associated with this lead status change.
        relatedCallEventId:
          type:
          - 'null'
          - string
          description: The related call event ID associated with this lead status change.
        isM

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leadping/refs/heads/main/openapi/leadping-leadstatuschanges-api-openapi.yml