Leadping Conversations API

openapi: 3.2.0
info:
  title: Leadping Conversations 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: 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.
paths:
  /conversations/my:
    post:
      tags:
      - Conversations
      summary: List current user's inbox conversations
      description: Lists the current user's lead conversations with paging and sorting for inbox views, recent follow-up, and communication history.
      operationId: Conversations_GetAllForCurrentUser
      parameters:
      - name: archiveFilter
        in: query
        description: Optional filter selecting active, archived, or all lead conversations.
        schema:
          type: string
      requestBody:
        description: Pagination, filtering, and sorting options for the inbox.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
        required: true
      responses:
        '200':
          description: Returns the paged conversation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfConversationResponse'
        '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.
        '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.
        '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.
      security:
      - Bearer: []
      x-agentic-access:
        action-class: acting
        consequences:
        - write
        subject:
          required: true
        authorization:
          source: OpenAPI security requirements
          audience: https://api.leadping.ai
        audit:
          recommended: true
  /conversations/{id}/mark-read:
    post:
      tags:
      - Conversations
      summary: Marks an inbox conversation as read
      description: Updates the conversation's read state for the current user's inbox and returns whether the conversation was found.
      operationId: Conversations_MarkAsRead
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to mark as read.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: boolean
            application/json:
              schema:
                type: boolean
            text/json:
              schema:
                type: boolean
        '404':
          description: The requested 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.
        '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.
      security:
      - Bearer: []
      x-agentic-access:
        action-class: acting
        consequences:
        - write
        subject:
          required: true
        authorization:
          source: OpenAPI security requirements
          audience: https://api.leadping.ai
        audit:
          recommended: true
  /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:
              $ref: '#/components/schemas/RequestDataOptions'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
        required: true
      responses:
        '200':
          description: Returns the paged conversation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfConversationResponse'
        '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.
        '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.
        '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.
      security:
      - Bearer: []
      x-agentic-access:
        action-class: acting
        consequences:
        - write
        subject:
          required: true
        authorization:
          source: OpenAPI security requirements
          audience: https://api.leadping.ai
        audit:
          recommended: true
components:
  schemas:
    OrderByOption:
      required:
      - field
      type: object
      properties:
        field:
          type: string
        direction:
          enum:
          - asc
          - desc
          type:
          - 'null'
          - string
    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.
    IdNameValue:
      required:
      - id
      - name
      type: object
      properties:
        value:
          type:
          - 'null'
          - string
        id:
          type: string
        name:
          type: string
      description: Phone number used by this conversation response for calls, SMS, lookup, or routing.
    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.
    ExactMatchFilter:
      required:
      - field
      type: object
      properties:
        value: {}
        field:
          type: string
    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.
    RangeFilter:
      required:
      - field
      type: object
      properties:
        greaterThan: {}
        greaterThanOrEqual: {}
        lessThan: {}
        lessThanOrEqual: {}
        field:
          type: string
    PagedResultOfConversationResponse:
      type: object
      properties:
        items:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/ConversationResponse'
            description: Describes conversation data returned by Leadping.
        pageSize:
          type: integer
          format: int32
        totalCount:
          type:
          - 'null'
          - integer
          format: int32
        continuationToken:
          type:
          - 'null'
          - string
    RequestDataOptions:
      type: object
      properties:
        pageSize:
          type: integer
          format: int32
        continuationToken:
          type:
          - 'null'
          - string
        orderBy:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/OrderByOption'
        includeCount:
          type:
          - 'null'
          - boolean
        search:
          type:
          - 'null'
          - string
        searchFields:
          type:
          - 'null'
          - array
          items:
            type: string
        filters:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/ExactMatchFilter'
        rangeFilters:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/RangeFilter'
  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
    SourceKey:
      type: http
      description: 'Leadping source key for lead ingestion endpoints only using the Authorization header. Example: "Authorization: Bearer lp_src_...".'
      scheme: bearer
      bearerFormat: Leadping source key
externalDocs:
  description: Leadping API documentation, authentication guide, concepts, and integration guidance.
  url: https://leadping.ai/docs/api-reference