> ## Documentation Index
> Fetch the complete documentation index at: https://leadping.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set a lead's current status

> Sets the lead's current structured status and records the change for audit, automation, and reporting.



## OpenAPI

````yaml /openapi.json put /leads/{leadId}/status
openapi: 3.1.1
info:
  title: Leadping 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
security: []
tags:
  - name: leadping.Api
    description: >-
      Agent-to-agent discovery and request handling for Leadping's supported AI
      agent integrations.
  - name: Analytics
    description: >-
      Provides lead, communication, conversion, and organization performance
      analytics. Use these endpoints to measure activity over time, compare
      outcomes, and power operational dashboards and reporting workflows.
  - name: Automations
    description: >-
      Manages automated lead follow-up workflows and their execution history.
      Use these endpoints to configure SMS automation steps, preview eligible
      leads, run workflows, and inspect individual automation executions.
  - name: BlogArticles
    description: >-
      Provides published Leadping blog content. Use these endpoints to list
      published articles and retrieve an individual article by its public slug.
  - name: Conversations
    description: >-
      Provides lead conversation timelines and inbox-oriented conversation
      views. Use these endpoints to list recent conversations and retrieve the
      cross-channel communication history associated with a lead.
  - name: Feedback
    description: >-
      Captures Leadping product feedback and supports administrative triage.
      Users can submit feedback, while authorized staff can search, inspect,
      classify, and update feedback throughout the review process.
  - name: Leads
    description: >-
      Manages lead intake, records, assignment, routing, and lifecycle
      operations. Use these endpoints to ingest leads from trusted sources,
      search and update lead records, manage ownership and tags, and archive or
      delete leads.
  - 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.
  - name: LeadStatuses
    description: >-
      Manages the lead statuses used to classify and track leads throughout
      their lifecycle. Use these endpoints to list, create, update, and archive
      organization-specific lead statuses for consistent pipeline organization
      and reporting.
  - name: Notifications
    description: >-
      Manages user notifications, announcements, and push-notification
      installations. Use these endpoints to retrieve notification feeds and
      unread counts, update read state, and register or remove client push
      installations.
  - name: OutboundDelivery
    description: >-
      Reports outbound delivery pacing and sending capacity for the current
      organization. Use these endpoints to determine whether outbound
      communications can proceed and to understand active throttles, limits, or
      capacity constraints.
  - name: Sources
    description: >-
      Manages lead sources, intake credentials, routing defaults, and
      attribution. Use these endpoints to create and configure sources, search
      source records, inspect source activity, rotate intake access, and remove
      obsolete sources.
  - name: Suppressions
    description: >-
      Manages recipient suppression state for compliant Leadping communication
      workflows. Use these endpoints to check contact eligibility, record or
      release suppressions, and review suppression history before sending
      messages or placing calls.
  - name: Tags
    description: >-
      Manages organization-defined tags for categorizing and routing leads. Use
      these endpoints to list, create, update, and archive reusable tags that
      support lead filtering, automation, assignment, and reporting.
  - name: Users
    description: >-
      Manages the current Leadping user's profile, preferences, setup, and
      account workflows. Use these endpoints to retrieve and update user data,
      configure communication and compliance preferences, complete onboarding,
      manage plan-related actions, and request account operations.
  - name: Calls
    description: >-
      Manages outbound Leadping calls and active call-control workflows. Use
      these endpoints to initiate or cancel a call, retrieve call state, and
      transfer an active call within supported telephony flows.
  - name: PhoneNumbers
    description: >-
      Manages phone-number discovery, purchasing, assignment, configuration, and
      compliance. Use these endpoints to search available numbers, manage owned
      numbers and caller identity, configure messaging or voice behavior, and
      monitor registration and warmup state.
  - name: Sms
    description: >-
      Sends and manages SMS and MMS communications through Leadping. Use these
      endpoints to send messages, upload MMS media, and cancel eligible
      scheduled messages while preserving conversation and delivery tracking.
  - name: Telephony
    description: >-
      Provides shared authentication and bootstrap data for Leadping telephony
      clients. Use this endpoint to obtain the scoped credentials and
      configuration required to initialize supported calling experiences.
  - name: Organizations
    description: >-
      Manages Leadping organizations, memberships, invitations, settings, and
      API credentials. Use these endpoints to maintain organization profiles and
      branding, manage members and invitations, configure options, and issue or
      revoke organization API keys.
  - name: UserDataExports
    description: >-
      Creates and delivers user-requested exports of Leadping account data. Use
      these endpoints to request an export, monitor its preparation status, and
      download the completed archive through a time-limited redirect.
  - name: CallEvents
    description: >-
      Provides call event records for auditing, diagnostics, and reporting. Use
      these endpoints to search and inspect lifecycle events emitted as Leadping
      calls are initiated, connected, completed, or fail.
  - name: Events
    description: >-
      Provides a unified record of Leadping activity across communication
      channels. Use these endpoints to retrieve event timelines, search event
      history, inspect event details, and record supported application events.
  - name: SmsEvents
    description: >-
      Provides SMS and MMS event records for delivery tracking and diagnostics.
      Use these endpoints to search and inspect message lifecycle events,
      including outbound delivery updates and inbound messaging activity.
  - name: PaymentMethods
    description: >-
      Manages organization payment methods and billing invoices. Use these
      endpoints to add, confirm, inspect, and remove payment methods or retrieve
      invoices associated with the current organization's billing account.
  - name: Transactions
    description: >-
      Provides organization wallet and billing transaction records. Use these
      endpoints to search transaction history, inspect individual charges or
      credits, review transaction summaries, and issue administrative credits.
  - name: Usage
    description: >-
      Provides billable usage records for Leadping services. Use these endpoints
      to review messaging and calling consumption, inspect usage summaries, and
      reconcile provider activity for an organization.
  - name: Wallets
    description: >-
      Manages organization wallet balances, funding, and credit activity. Use
      these endpoints to inspect wallet state and history, configure wallet
      behavior, add funds, and record credits or adjustments.
externalDocs:
  description: >-
    Leadping API documentation, authentication guide, concepts, and integration
    guidance.
  url: https://leadping.ai/docs/api-reference
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.
        '400':
          description: The request was invalid or malformed.
          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.
              example:
                type: about:blank
                title: Bad Request
                status: 400
                detail: The request could not be completed.
        '401':
          description: Authentication credentials are missing or invalid.
          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.
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: The request could not be completed.
        '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.
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: The request could not be completed.
        '404':
          description: A related resource was not found.
          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.
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: The request could not be completed.
        '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.
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: The request could not be completed.
      security:
        - Bearer: []
components:
  schemas:
    LeadStatusChangeRequest:
      required:
        - type
        - outcome
      type: object
      properties:
        type:
          type: string
          description: Category of status change being 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.
        notes:
          type:
            - 'null'
            - 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.
        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.
      description: >-
        Defines a lead status transition or correction, including its target
        status, effective time, source, and explanatory context.
    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.
        isMissedCallFollowUp:
          type: boolean
          description: Whether this lead status change is missed call follow up.
        sourceId:
          type:
            - 'null'
            - string
          description: The source ID associated with this lead status change.
      description: >-
        Describes an auditable lead status transition, including the previous
        and new status, source, actor, and effective time.
    ProblemDetails:
      type: object
      properties:
        type:
          type:
            - 'null'
            - string
          description: URI reference that identifies the problem type.
        title:
          type:
            - 'null'
            - string
          description: Short, human-readable summary of the problem.
        status:
          type:
            - 'null'
            - integer
          description: HTTP status code returned for the problem.
          format: int32
        detail:
          type:
            - 'null'
            - string
          description: >-
            Human-readable explanation specific to this occurrence of the
            problem.
        instance:
          type:
            - 'null'
            - string
          description: >-
            URI reference that identifies this specific occurrence of the
            problem.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Validation errors keyed by the JSON request field name. Present for
            request validation failures.
        traceId:
          type: string
          description: >-
            Request trace identifier used to correlate this problem with
            Leadping diagnostics.
      description: >-
        Standard problem-details response containing machine-readable and
        human-readable information about an HTTP API error.
  securitySchemes:
    Bearer:
      type: http
      description: >-
        Authorization header using the Bearer scheme. Accepted values are
        Leadping user JWT access tokens and WorkOS organization API keys
        beginning with sk_.
      scheme: bearer
      bearerFormat: JWT or organization API key

````