> ## 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.

# List inbox conversations for a lead

> Lists conversations for one lead, helping users inspect communication threads, recent follow-up, and related events.



## OpenAPI

````yaml /openapi.json post /conversations/lead/{leadId}
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:
  /conversations/lead/{leadId}:
    post:
      tags:
        - Conversations
      summary: List inbox conversations for a lead
      description: >-
        Lists conversations for one lead, helping users inspect communication
        threads, recent follow-up, and related events.
      operationId: Conversations_GetConversationsByLead
      parameters:
        - name: leadId
          in: path
          description: The lead ID to get conversations for.
          required: true
          schema:
            type: string
      requestBody:
        description: >-
          Pagination, filtering, and sorting options for the lead's
          conversations.
        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: Returns the paged conversation response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PagedResultOfConversationResponse'
                description: >-
                  Returns one page of query results together with page-size,
                  optional total-count, and opaque continuation-cursor metadata.
        '400':
          description: The request was invalid or failed validation.
          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.
        '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.
        '500':
          description: An unexpected server error occurred.
          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: Internal Server Error
                status: 500
                detail: The request could not be completed.
      security:
        - Bearer: []
components:
  schemas:
    RequestDataOptions:
      type: object
      properties:
        pageSize:
          type: integer
          description: >-
            Maximum number of items requested for one page; the server may
            enforce a lower maximum or apply a default.
          format: int32
        continuationToken:
          type:
            - 'null'
            - string
          description: >-
            Opaque cursor returned by the previous paged response; omit it when
            requesting the first page and do not parse or modify it.
        orderBy:
          type:
            - 'null'
            - array
          items:
            allOf:
              - $ref: '#/components/schemas/OrderByOption'
            description: >-
              Defines one field and direction used to order an API query result
              set.
          description: >-
            Sort instructions applied in priority order, with the first entry
            acting as the primary sort.
        includeCount:
          type:
            - 'null'
            - boolean
          description: >-
            Whether the response should include the total number of matching
            records; counting may increase query cost or latency.
        search:
          type:
            - 'null'
            - string
          description: Free-text search term applied to the configured SearchFields.
        searchFields:
          type:
            - 'null'
            - array
          items:
            type: string
          description: >-
            Serializable string field names searched for Search; supported names
            are determined by the queried resource.
        filters:
          type:
            - 'null'
            - array
          items:
            allOf:
              - $ref: '#/components/schemas/ExactMatchFilter'
            description: Selects records whose named field equals a supplied scalar value.
          description: >-
            Exact-match conditions that require each named field to equal its
            supplied value.
        rangeFilters:
          type:
            - 'null'
            - array
          items:
            allOf:
              - $ref: '#/components/schemas/RangeFilter'
            description: >-
              Selects records by applying inclusive or exclusive lower and upper
              bounds to a named comparable field.
          description: >-
            Range conditions that constrain comparable fields with inclusive or
            exclusive lower and upper bounds.
      description: >-
        Defines cursor pagination, sorting, search, exact-match filters, and
        range filters for a structured API query.
    PagedResultOfConversationResponse:
      type: object
      properties:
        items:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/ConversationResponse'
            description: Describes conversation data returned by Leadping.
          description: >-
            Items included in the current page, in the order determined by the
            query.
        pageSize:
          type: integer
          description: >-
            Effective page-size limit used for this response, which may differ
            from the requested size because of server defaults or limits.
          format: int32
        totalCount:
          type:
            - 'null'
            - integer
          description: >-
            Total number of records matching the query across all pages, or null
            when counting was not requested or computed.
          format: int32
        continuationToken:
          type:
            - 'null'
            - string
          description: >-
            Opaque cursor for requesting the next page, or null when no
            additional page is available; clients must not parse or modify it.
      description: >-
        Returns one page of query results together with page-size, optional
        total-count, and opaque continuation-cursor metadata.
    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.
    OrderByOption:
      required:
        - field
      type: object
      properties:
        field:
          type: string
          description: >-
            Serializable field name used for sorting; supported names are
            determined by the queried resource.
        direction:
          enum:
            - asc
            - desc
          type:
            - 'null'
            - string
          description: >-
            Identifies whether query results are ordered from lower to higher
            values or from higher to lower values.
      description: Defines one field and direction used to order an API query result set.
    ExactMatchFilter:
      required:
        - field
      type: object
      properties:
        value:
          description: >-
            Scalar value the target field must equal; its JSON type should match
            the field being queried.
        field:
          type: string
          description: >-
            Serializable field name to evaluate; supported names are determined
            by the queried resource.
      description: Selects records whose named field equals a supplied scalar value.
    RangeFilter:
      required:
        - field
      type: object
      properties:
        greaterThan:
          description: >-
            Exclusive lower bound; matching field values must be greater than
            this value.
        greaterThanOrEqual:
          description: >-
            Inclusive lower bound; matching field values must be greater than or
            equal to this value.
        lessThan:
          description: >-
            Exclusive upper bound; matching field values must be less than this
            value.
        lessThanOrEqual:
          description: >-
            Inclusive upper bound; matching field values must be less than or
            equal to this value.
        field:
          type: string
          description: >-
            Serializable field name to evaluate; supported names are determined
            by the queried resource.
      description: >-
        Selects records by applying inclusive or exclusive lower and upper
        bounds to a named comparable field.
    ConversationResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique Leadping identifier for this conversation response.
        leadId:
          type: string
          description: Lead ID associated with this inbox conversation.
        firstName:
          type:
            - 'null'
            - string
          description: >-
            First name of the lead, user, or contact represented by this
            conversation response.
        lastName:
          type:
            - 'null'
            - string
          description: >-
            Last name of the lead, user, or contact represented by this
            conversation response.
        email:
          type:
            - 'null'
            - string
          description: Email address used to resolve the lead's avatar when available.
          format: email
        avatarUrl:
          type:
            - 'null'
            - string
          description: Optional profile image URL explicitly associated with the lead.
          format: uri
        lastSnippet:
          type:
            - 'null'
            - string
          description: Most recent message preview shown for the conversation.
        lastEventAt:
          type:
            - 'null'
            - string
          description: UTC timestamp when the most recent conversation event occurred.
          format: date-time
        lastEventIsInternalNote:
          type: boolean
          description: >-
            Indicates that the most recent conversation activity is an internal
            note.
        status:
          enum:
            - needs_reply
            - waiting
            - failed
            - open
          type:
            - 'null'
            - string
          description: >-
            Defines the customer-facing operational status for an inbox
            conversation.
        statusReason:
          type:
            - 'null'
            - string
          description: >-
            Human-readable reason explaining the current status of this
            conversation response.
        archivedAt:
          type:
            - 'null'
            - string
          description: UTC timestamp when this record was archived.
          format: date-time
        archiveReason:
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
          type:
            - 'null'
            - integer
          description: Defines why a lead was removed from the active working pipeline.
          format: int32
        isArchived:
          type: boolean
          description: Indicates whether the Leadping conversation has been archived.
        currentLeadStatus:
          type:
            - 'null'
            - object
          allOf:
            - $ref: '#/components/schemas/CurrentLeadStatusSummary'
          description: Current lead status change summary that describes the lead outcome.
        nextStep:
          type:
            - 'null'
            - string
          description: Recommended next step to move this conversation response forward.
        isUnread:
          type: boolean
          description: >-
            Indicates whether the current user has unread activity in the
            conversation.
        phoneNumber:
          type:
            - 'null'
            - object
          allOf:
            - $ref: '#/components/schemas/IdNameValue'
          description: >-
            Phone number used by this conversation response for calls, SMS,
            lookup, or routing.
        leadPhoneNumber:
          type:
            - 'null'
            - string
          description: Lead's phone number used for conversation matching and outreach.
        outboundPhoneNumberOverrideId:
          type:
            - 'null'
            - string
          description: >-
            Phone number ID manually chosen to override automatic outbound
            selection.
        activeOutboundPhoneNumberId:
          type:
            - 'null'
            - string
          description: Phone number ID currently active for outbound delivery.
      description: Describes conversation data returned by Leadping.
    CurrentLeadStatusSummary:
      type: object
      properties:
        id:
          type:
            - 'null'
            - string
          description: >-
            Unique Leadping identifier for this current lead status change
            summary.
        category:
          enum:
            - Open
            - Qualified
            - Converted
            - Lost
            - Invalid
            - Duplicate
          type:
            - 'null'
            - string
          description: >-
            Controlled lead status change categories used for reporting,
            automation, and analytics.
        outcome:
          type:
            - 'null'
            - string
          description: Current lead status change outcome assigned to the lead.
        displayName:
          type: string
          description: >-
            Human-readable display name shown for this current lead status
            change summary.
        changedAt:
          type:
            - 'null'
            - string
          description: UTC timestamp when the lead status change last changed.
          format: date-time
        changedByUserId:
          type:
            - 'null'
            - string
          description: User ID of the person who last changed the lead status change.
        changedByAutomationId:
          type:
            - 'null'
            - string
          description: Automation ID that last changed the lead status change.
        source:
          enum:
            - User
            - AI
            - Automation
            - System
            - API
          type:
            - 'null'
            - string
          description: Known sources that can change a lead's current lead status change.
      description: >-
        Summary schema for Leadping API current lead status change summary data
        used in dashboards and reports.
    IdNameValue:
      required:
        - id
        - name
      type: object
      properties:
        value:
          type:
            - 'null'
            - string
          description: >-
            Optional machine-readable or display value associated with the
            referenced resource.
        id:
          type: string
          description: Stable unique identifier of the referenced resource.
        name:
          type: string
          description: Human-readable display name of the referenced resource.
      description: >-
        Extends an identifier-and-name resource reference with an optional
        string value used for display or selection metadata.
  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

````