openapi: 3.2.0
info:
title: Leadping Calls 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: 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.
paths:
/phone-call/initiate:
post:
tags:
- Calls
summary: Initiate a Leadping phone call
description: Starts an outbound Leadping phone call for an authenticated user and returns the provider call identifiers, status, and routing details.
operationId: Calls_InitiateCall
requestBody:
description: The call initiation request containing phone number and optional metadata.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/InitiateCallRequest'
description: Defines the fields clients can send when working with phone call initiation.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/InitiateCallRequest'
description: Defines the fields clients can send when working with phone call initiation.
required: true
responses:
'200':
description: Calls was successfully initiated.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneCallResponse'
description: Describes a Leadping phone call, including participants, direction, provider state, timing, recording, and billing details.
'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: []
/phone-call/{callId}/hangup:
post:
tags:
- Calls
summary: End an active Leadping phone call
description: Ends an active Leadping phone call by call ID and returns the updated call record, including status and provider routing details.
operationId: Calls_HangupCall
parameters:
- name: callId
in: path
description: The unique identifier of the call to end.
required: true
schema:
type: string
responses:
'200':
description: Calls was successfully ended.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneCallResponse'
description: Describes a Leadping phone call, including participants, direction, provider state, timing, recording, and billing details.
'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.
'404':
description: The specified call 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: []
/phone-call/{callId}/status:
get:
tags:
- Calls
summary: Get the status of a Leadping phone call
description: Retrieves the latest status for a Leadping phone call by call ID, including provider state and call details for tracking progress.
operationId: Calls_GetCallStatus
parameters:
- name: callId
in: path
description: The unique identifier of the call to check.
required: true
schema:
type: string
responses:
'200':
description: Calls status was successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneCallResponse'
description: Describes a Leadping phone call, including participants, direction, provider state, timing, recording, and billing details.
'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: []
/phone-call/{callId}/transfer:
post:
tags:
- Calls
summary: Transfer an active Leadping phone call
description: Transfers an active Leadping phone call to a new phone number and returns the updated call record with status and routing details.
operationId: Calls_TransferCall
parameters:
- name: callId
in: path
description: The unique identifier of the call to transfer.
required: true
schema:
type: string
- name: newPhoneNumber
in: query
description: The phone number to transfer the call to.
schema:
type: string
responses:
'200':
description: Calls was successfully transferred.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneCallResponse'
description: Describes a Leadping phone call, including participants, direction, provider state, timing, recording, and billing details.
'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.
'404':
description: The specified call 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: []
components:
schemas:
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.
PhoneCallResponse:
type: object
properties:
status:
allOf:
- $ref: '#/components/schemas/PhoneCallStatus'
description: Current lifecycle status for this phone call in the Leadping API.
statusReason:
type:
- 'null'
- string
description: Human-readable reason explaining the current status of this phone call.
direction:
type:
- 'null'
- string
description: Communication direction for this phone call, such as inbound or outbound.
conversationId:
type:
- 'null'
- string
description: Conversation ID that links this phone call to the Leadping inbox thread.
leadId:
type:
- 'null'
- string
description: Lead ID associated with the call conversation or outreach attempt.
phoneNumber:
type: string
description: Phone number used by this phone call for calls, SMS, lookup, or routing.
toPhoneNumber:
type:
- 'null'
- string
description: Recipient phone number used for this communication.
fromPhoneNumberId:
type:
- 'null'
- string
description: Sender phone number ID used for this outbound SMS or call.
fromPhoneNumber:
type:
- 'null'
- string
description: Sender phone number used for this communication.
callerId:
type:
- 'null'
- string
description: Caller ID phone number presented during the outbound call.
selectionReason:
enum:
- StickyConversation
- LeadAssigned
- CampaignOrSource
- Preferred
- LocalArea
- HealthyPool
- FallbackDefault
- ManualOverride
type:
- 'null'
- string
description: Explains why Leadping selected, rejected, or substituted an outgoing caller or messaging number.
wasManuallyOverridden:
type: boolean
description: Indicates whether a user manually overrode Leadping's automatic number selection for this phone call.
campaignId:
type:
- 'null'
- string
description: Messaging campaign identifier associated with this phone call.
sourceId:
type:
- 'null'
- string
description: Lead source ID used for attribution and routing on this call.
endedAt:
type:
- 'null'
- string
description: UTC timestamp when the call ended.
format: date-time
queuedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping queued this phone call for processing.
format: date-time
ringingAt:
type:
- 'null'
- string
description: UTC timestamp when the call started ringing.
format: date-time
answeredAt:
type:
- 'null'
- string
description: UTC timestamp when the call was answered.
format: date-time
durationSeconds:
type:
- 'null'
- integer
description: Call duration in seconds.
format: int32
billingStatus:
type:
- 'null'
- string
description: Billing state for this communication, charge, or transaction.
billableAmount:
type:
- 'null'
- number
description: Monetary amount billed for this Leadping communication or transaction.
format: double
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.
id:
type: string
description: Stable unique identifier of the resource.
createdAt:
type: string
description: UTC timestamp when the resource was created.
format: date-time
modifiedAt:
type:
- 'null'
- string
description: UTC timestamp when the resource was last modified, or null when it has not been updated.
format: date-time
description: Describes a Leadping phone call, including participants, direction, provider state, timing, recording, and billing details.
InitiateCallRequest:
required:
- leadId
type: object
properties:
fromPhoneNumberId:
type:
- 'null'
- string
description: Sender phone number ID used for this outbound SMS or call.
conversationId:
type:
- 'null'
- string
description: Conversation ID that links this phone call initiation request to the Leadping inbox thread.
leadId:
type: string
description: Lead ID associated with the outbound call request.
wasManuallyOverridden:
type: boolean
description: Indicates whether a user manually overrode Leadping's automatic number selection for this phone call initiation request.
campaignId:
type:
- 'null'
- string
description: Messaging campaign identifier associated with this phone call initiation request.
sourceId:
type:
- 'null'
- string
description: Lead source ID used for call attribution and sender selection.
outboundIdempotencyKey:
type:
- 'null'
- string
description: Idempotency key used to prevent duplicate outbound delivery.
description: Defines the fields clients can send when working with phone call initiation.
example:
leadId: lead-123
conversationId: conversation-123
wasManuallyOverridden: false
outboundIdempotencyKey: call-example-001
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
PhoneCallStatus:
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: string
description: Describes the durable business outcome of a Leadping phone call after provider status normalization.
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