Leadping Call Events API

openapi: 3.2.0
info:
  title: Leadping Call Events 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: 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.
paths:
  /events/calls/all/my:
    post:
      tags:
      - CallEvents
      summary: List current-user lead call event history
      description: Lists call events visible to the current user with paging, sorting, and filters for call history and lead follow-up review.
      operationId: CallEvents_GetAllForCurrentUser
      requestBody:
        description: Pagination, filtering, and sorting options.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
        required: true
      responses:
        '200':
          description: Call events were successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfCallEventTableRow'
        '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.
        '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
  /events/calls/{callEventId}:
    get:
      tags:
      - CallEvents
      summary: Get lead call event details by event ID
      description: Returns one call event, including call metadata, provider status, related lead, and communication context.
      operationId: CallEvents_GetById
      parameters:
      - name: callEventId
        in: path
        description: The ID of the call event to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the call event table row.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CallEventTableRow'
                description: Summarizes call event data in paginated and searchable results.
        '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: connected
        consequences:
        - read
        subject:
          required: true
        authorization:
          source: OpenAPI security requirements
          audience: https://api.leadping.ai
        audit:
          recommended: false
  /events/calls/lead/{leadId}:
    post:
      tags:
      - CallEvents
      summary: List call event history for an organization lead
      description: Lists call events for one lead with paging, helping users review call attempts, outcomes, and follow-up history.
      operationId: CallEvents_GetByLeadId
      parameters:
      - name: leadId
        in: path
        description: The ID of the lead.
        required: true
        schema:
          type: string
      requestBody:
        description: Pagination, filtering, and sorting options.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
        required: true
      responses:
        '200':
          description: Returns the paged call event table row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfCallEventTableRow'
        '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.
      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
  /events/calls/phone/{phoneNumber}:
    post:
      tags:
      - CallEvents
      summary: List call event history for a phone number
      description: Lists call events for one phone number with paging, helping users review volume, outcomes, and communication history.
      operationId: CallEvents_GetByPhoneNumber
      parameters:
      - name: phoneNumber
        in: path
        description: The phone number to search for.
        required: true
        schema:
          type: string
      requestBody:
        description: Pagination, filtering, and sorting options.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RequestDataOptions'
        required: true
      responses:
        '200':
          description: Returns the paged call event table row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfCallEventTableRow'
        '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.
      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
    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
    PagedResultOfCallEventTableRow:
      type: object
      properties:
        items:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CallEventTableRow'
            description: Summarizes call event data in paginated and searchable results.
        pageSize:
          type: integer
          format: int32
        totalCount:
          type:
          - 'null'
          - integer
          format: int32
        continuationToken:
          type:
          - 'null'
          - string
    RangeFilter:
      required:
      - field
      type: object
      properties:
        greaterThan: {}
        greaterThanOrEqual: {}
        lessThan: {}
        lessThanOrEqual: {}
        field:
          type: string
    CallEventTableRow:
      type: object
      properties:
        id:
          type: string
          description: Unique Leadping identifier for this call event table row.
        leadId:
          type:
          - 'null'
          - string
          description: Lead ID associated with this call event.
        leadName:
          type:
          - 'null'
          - string
          description: Display name for the lead associated with this call event.
        organizationId:
          type:
          - 'null'
          - string
          description: Organization ID associated with this call event.
        userId:
          type:
          - 'null'
          - string
          description: User ID associated with the person or agent who initiated this call event.
        userName:
          type:
          - 'null'
          - string
          description: Display name for the person or agent who initiated this call event.
        userEmail:
          type:
          - 'null'
          - string
          description: Email address for the person or agent who initiated this call event.
          format: email
        conversationId:
          type:
          - 'null'
          - string
          description: Conversation ID that links this call event table row to the Leadping inbox thread.
        fromPhoneNumberId:
          type:
          - 'null'
          - string
          description: Sender phone number ID used for this outbound SMS or call.
        fromPhoneNumber:
          type: string
          description: Sender phone number used for this communication.
        toPhoneNumber:
          type: string
          description: Recipient phone number used for this communication.
        callerId:
          type:
          - 'null'
          - string
          description: Caller ID phone number presented during the outbound call.
        status:
          enum:
          - scheduled
          - queued
          - initiated
          - ringing
          - in_progress
          - active
          - completed
          - ended
          - busy
          - no_answer
          - failed
          - canceled
          - missed
          - transferred
          - voicemail
          - blocked_billing
          - blocked_phone_number_status
          - blocked_configuration
          - blocked_permission
          - configuration_required
          type:
          - 'null'
          - string
          description: Describes the durable business outcome of a Leadping phone call after provider status normalization.
        statusReason:
          type:
          - 'null'
          - string
          description: Human-readable reason explaining the current status of this call event table row.
        direction:
          type: string
          description: Communication direction for this call event table row, such as inbound or outbound.
        createdAt:
          type: string
          description: UTC timestamp when this call event table row was created.
          format: date-time
        answeredAt:
          type:
          - 'null'
          - string
          description: UTC timestamp when the call was answered.
          format: date-time
        endedAt:
          type:
          - 'null'
          - string
          description: UTC timestamp when the call ended.
          format: date-time
        duration:
          type:
          - 'null'
          - integer
          description: Call duration or processing duration represented by this call event table row.
          format: int32
        billableSeconds:
          type:
          - 'null'
          - integer
          description: Billable call duration in seconds.
          format: int32
        billableAmount:
          type:
          - 'null'
          - number
          description: Monetary amount billed for this Leadping communication or transaction.
          format: double
        billingStatus:
          type:
          - 'null'
          - string
          description: Billing state for this communication, charge, or transaction.
        voicemailUrl:
          type:
          - 'null'
          - string
          description: URL for voicemail audio, when the call resulted in a voicemail.
          format: uri
        consoleEntries:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CommunicationConsoleEntry'
            description: Describes one durable diagnostic entry from the processing of a communication.
          description: Ordered diagnostic entries recorded while Leadping processed this call.
        user:
          type: string
          description: User summary connected to this call event table row.
        organization:
          type: string
          description: Organization summary connected to this call event table row.
        organizationName:
          type:
          - 'null'
          - string
          description: Display name for the organization associated with this call event.
      description: Summarizes call event data in paginated and searchable results.
    CommunicationConsoleEntry:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of this diagnostic console entry.
        stage:
          type: string
          description: Communication-processing stage that produced the entry, such as validation, routing, or provider delivery.
        status:
          type: string
          description: Outcome or state recorded for this processing stage.
        message:
          type: string
          description: User-safe diagnostic message describing what occurred at this stage.
        occurredAt:
          type: string
          description: UTC timestamp when this communication-processing event occurred.
          format: date-time
      description: Describes one durable diagnostic entry from the processing of a communication.
    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