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:
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: Call events were successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfCallEventTableRow'
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 malformed.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
/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/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
/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:
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 call event table row.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfCallEventTableRow'
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/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
/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:
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 call event table row.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfCallEventTableRow'
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/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
components:
schemas:
PagedResultOfCallEventTableRow:
type: object
properties:
items:
type: array
items:
allOf:
- $ref: '#/components/schemas/CallEventTableRow'
description: Summarizes call event data in paginated and searchable results.
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.
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.
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.
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.
recordingUrl:
type:
- 'null'
- string
description: URL for the call recording, when the provider makes one available.
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.
OrderByOption:
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:
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.
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.
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
example:
type: https://leadping.ai/docs/errors/validation
title: Request validation failed
status: 400
detail: One or more request fields are invalid.
instance: /leads/intake
RangeFilter:
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.
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