openapi: 3.2.0
info:
title: Leadping Phone Numbers 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: 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.
paths:
/phone-numbers/search:
post:
tags:
- PhoneNumbers
summary: Search purchasable organization phone numbers
description: Searches available phone numbers for purchase, applying country, area, and capability filters for lead communication setup.
operationId: PhoneNumbers_Search
requestBody:
description: Area code, locality, capabilities, and quantity filters for available phone numbers.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneNumberSearchRequest'
description: Defines the fields clients can send when working with phone number search.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneNumberSearchRequest'
description: Defines the fields clients can send when working with phone number search.
required: true
responses:
'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.
'500':
description: An unexpected server error occurred.
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.
'200':
description: Returns the phone number search response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneNumberSearchResponse'
description: Describes phone number search data returned by Leadping.
'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-numbers/all/organization:
post:
tags:
- PhoneNumbers
summary: List current-organization phone numbers
description: Lists phone numbers visible to the current organization with paging, sorting, and filters for messaging, calling, and warmup management.
operationId: PhoneNumbers_GetAllForCurrentOrganization
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: Phone numbers were successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfPhoneNumberTableRow'
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: []
/phone-numbers/outgoing/conversation/{conversationId}:
post:
tags:
- PhoneNumbers
summary: Select conversation sender number
description: Selects the outgoing phone number for an existing conversation, considering assignments, overrides, and delivery eligibility.
operationId: PhoneNumbers_GetOutgoingForConversation
parameters:
- name: conversationId
in: path
description: The conversation identifier.
required: true
schema:
type: string
requestBody:
description: The outgoing number selection request payload for the operation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionRequest'
description: Defines the fields clients can send when working with outgoing number selection.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionRequest'
description: Defines the fields clients can send when working with outgoing number selection.
required: true
responses:
'200':
description: Returns the outgoing number selection response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionResponse'
description: Describes outgoing number selection data returned by Leadping.
'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: []
/phone-numbers/outgoing/new:
post:
tags:
- PhoneNumbers
summary: Select new lead sender number
description: Selects an outgoing phone number for a new outbound lead message using destination, source, and delivery eligibility rules.
operationId: PhoneNumbers_GetOutgoingForNewOutbound
requestBody:
description: The outgoing number selection request payload for the operation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionRequest'
description: Defines the fields clients can send when working with outgoing number selection.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionRequest'
description: Defines the fields clients can send when working with outgoing number selection.
required: true
responses:
'200':
description: Returns the outgoing number selection response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionResponse'
description: Describes outgoing number selection data returned by Leadping.
'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: []
/phone-numbers/outgoing/manual-override:
post:
tags:
- PhoneNumbers
summary: Validate sender number override
description: Validates a manual outgoing-number override before use, checking ownership, destination, and delivery eligibility.
operationId: PhoneNumbers_ValidateManualOverride
requestBody:
description: The outgoing number manual override request payload for the operation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberManualOverrideRequest'
description: Defines the fields clients can send when working with outgoing number manual override.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberManualOverrideRequest'
description: Defines the fields clients can send when working with outgoing number manual override.
required: true
responses:
'200':
description: Returns the outgoing number selection response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionResponse'
description: Describes outgoing number selection data returned by Leadping.
'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: []
/phone-numbers/outgoing/conversation/{conversationId}/override:
post:
tags:
- PhoneNumbers
summary: Set sender number override
description: Sets the outgoing phone number override for a conversation so future lead messages use the selected eligible number.
operationId: PhoneNumbers_SetConversationOverride
parameters:
- name: conversationId
in: path
description: The conversation identifier.
required: true
schema:
type: string
requestBody:
description: The outgoing number manual override request payload for the operation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberManualOverrideRequest'
description: Defines the fields clients can send when working with outgoing number manual override.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberManualOverrideRequest'
description: Defines the fields clients can send when working with outgoing number manual override.
required: true
responses:
'200':
description: Returns the outgoing number selection response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionResponse'
description: Describes outgoing number selection data returned by Leadping.
'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: []
delete:
tags:
- PhoneNumbers
summary: Clear sender number override
description: Clears a conversation's outgoing-number override so future lead messages return to automatic number selection.
operationId: PhoneNumbers_ClearConversationOverride
parameters:
- name: conversationId
in: path
description: The conversation identifier.
required: true
schema:
type: string
responses:
'200':
description: Returns the outgoing number selection response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OutgoingNumberSelectionResponse'
description: Describes outgoing number selection data returned by Leadping.
'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: []
/phone-numbers/{phoneNumberId}:
get:
tags:
- PhoneNumbers
summary: Get organization phone number details by ID
description: Returns one phone number visible to the current user, including messaging status, assignment, warmup, and purchase metadata.
operationId: PhoneNumbers_Get
parameters:
- name: phoneNumberId
in: path
description: The phone number identifier.
required: true
schema:
type: string
responses:
'200':
description: Returns the phone number response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneNumberResponse'
description: Describes a Leadping-managed phone number, including capabilities, messaging registration, health, and assignment details.
'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: []
put:
tags:
- PhoneNumbers
summary: Update organization phone number settings
description: Updates phone number settings such as its optional label, assignment, messaging options, or warmup configuration.
operationId: PhoneNumbers_Update
parameters:
- name: phoneNumberId
in: path
description: The ID of the phone number to update.
required: true
schema:
type: string
requestBody:
description: The updated phone number details.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneNumberRequest'
description: Defines the fields clients can send when working with phone number update.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneNumberRequest'
description: Defines the fields clients can send when working with phone number update.
required: true
responses:
'200':
description: Returns the phone number response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PhoneNumberResponse'
description: Describes a Leadping-managed phone number, including capabilities, messaging registration, health, and assignment details.
'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.
'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.
'500':
description: An unexpected server error occurred.
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: []
delete:
tags:
- PhoneNumbers
summary: Delete an organization phone number by ID
description: Deletes a phone number from the current organization when it should no longer be used for lead communication.
operationId: PhoneNumbers_Delete
parameters:
- name: phoneNumberId
in: path
description: The ID of the phone number to delete.
required: true
schema:
type: string
responses:
'204':
description: No content is returned when the operation succeeds.
'400':
description: The request was invalid or failed validation.
content:
text/plain:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
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.
text/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
# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leadping/refs/heads/main/openapi/leadping-phonenumbers-api-openapi.yml