openapi: 3.2.0
info:
title: Leadping Usage 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: Usage
description: Provides billable usage records for Leadping services. Use these endpoints to review messaging and calling consumption, inspect usage summaries, and reconcile provider activity for an organization.
paths:
/usage/all/my:
post:
tags:
- Usage
summary: List organization messaging usage ledger entries
description: Lists current-organization usage ledger entries with paging, sorting, and filters for messaging, billing, and wallet review.
operationId: Usage_GetAllForCurrentOrganization
requestBody:
description: The filtering, sorting, and pagination 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 usage ledger table row.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfUsageLedgerTableRow'
description: Returns one page of query results together with page-size, optional total-count, and opaque continuation-cursor metadata.
'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: []
/usage/summary/my:
get:
tags:
- Usage
summary: Get organization messaging usage summary
description: Returns current-organization usage totals for the active billing period, including spend, limits, and event summary data.
operationId: Usage_GetSummaryForCurrentOrganization
parameters:
- name: periodStart
in: query
description: The period start.
schema:
type: string
format: date-time
- name: periodEnd
in: query
description: The period end.
schema:
type: string
format: date-time
responses:
'200':
description: Returns the usage summary response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/UsageSummaryResponse'
description: Describes usage summary response data used 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: []
components:
schemas:
UsageLedgerTableRow:
type: object
properties:
id:
type: string
description: Unique Leadping identifier for this usage ledger.
organization:
type:
- 'null'
- object
allOf:
- $ref: '#/components/schemas/IdNamePair'
description: Identifier and display name of the related organization.
user:
type:
- 'null'
- object
allOf:
- $ref: '#/components/schemas/IdNamePair'
description: Identifier and display name of the related user.
lead:
type:
- 'null'
- object
allOf:
- $ref: '#/components/schemas/IdNamePair'
description: Identifier and display name of the related lead.
phoneNumberId:
type:
- 'null'
- string
description: The phone number ID associated with this usage ledger.
phoneNumber:
type:
- 'null'
- string
description: The phone number associated with this usage ledger.
channel:
allOf:
- $ref: '#/components/schemas/UsageChannel'
description: Channel for this usage ledger.
billableUnit:
allOf:
- $ref: '#/components/schemas/BillableUnit'
description: Billable unit for this usage ledger.
status:
allOf:
- $ref: '#/components/schemas/UsageStatus'
description: The current status for this usage ledger.
quantity:
type: number
description: Quantity for this usage ledger.
format: double
durationSeconds:
type:
- 'null'
- integer
description: Duration seconds for this usage ledger.
format: int32
billableSeconds:
type:
- 'null'
- integer
description: Billable seconds for this usage ledger.
format: int32
smsSegments:
type:
- 'null'
- integer
description: SMS segments for this usage ledger.
format: int32
unitPrice:
type: number
description: Unit price for this usage ledger.
format: double
customerChargeAmount:
type: number
description: The monetary customer charge amount for this usage ledger.
format: double
isBillable:
type: boolean
description: Whether this usage ledger is billable.
description:
type:
- 'null'
- string
description: The human-readable description of this usage ledger.
createdAt:
type: string
description: UTC timestamp for created at on this usage ledger.
format: date-time
description: Describes usage ledger data used in Leadping API requests and responses.
UsageStatus:
enum:
- recorded
- rated
- pending_invoice
- invoiced
- charged
- failed
- refunded_credited
- non_billable_internal
- blocked_due_to_billing
type: string
description: Describes whether a metered usage record is pending, rated, billed, reconciled, excluded, or failed.
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.
UsageSummaryLine:
type: object
properties:
channel:
allOf:
- $ref: '#/components/schemas/UsageChannel'
description: Channel for this usage summary line.
billableUnit:
allOf:
- $ref: '#/components/schemas/BillableUnit'
description: Billable unit for this usage summary line.
status:
allOf:
- $ref: '#/components/schemas/UsageStatus'
description: The current status for this usage summary line.
quantity:
type: number
description: Quantity for this usage summary line.
format: double
customerChargeAmount:
type: number
description: The monetary customer charge amount for this usage summary line.
format: double
recordCount:
type: integer
description: The record count for this usage summary line.
format: int32
description: Describes usage summary line data used in Leadping API requests and responses.
UsageSummaryResponse:
type: object
properties:
periodStart:
type: string
description: UTC timestamp for period start on this usage summary.
format: date-time
periodEnd:
type: string
description: UTC timestamp for period end on this usage summary.
format: date-time
customerChargeTotal:
type: number
description: The customer charge total for this usage summary.
format: double
billableQuantityTotal:
type: number
description: The billable quantity total for this usage summary.
format: double
transactionCount:
type: integer
description: The usage record count for this usage summary.
format: int32
pendingInvoiceCount:
type: integer
description: The pending invoice count for this usage summary.
format: int32
failedCount:
type: integer
description: The failed count for this usage summary.
format: int32
lines:
type: array
items:
allOf:
- $ref: '#/components/schemas/UsageSummaryLine'
description: Describes usage summary line data used in Leadping API requests and responses.
description: The lines included with this usage summary.
counters:
type: array
items:
allOf:
- $ref: '#/components/schemas/UsageCounterLine'
description: Describes one named usage total displayed in organization billing and activity summaries.
description: The named usage counters included with this usage summary.
description: Describes usage summary response data used by Leadping.
UsageCounterLine:
type: object
properties:
key:
type: string
description: The stable key for this usage counter.
label:
type: string
description: The human-readable label for this usage counter.
value:
type: number
description: Numeric for this usage counter.
format: double
unit:
type: string
description: The unit label for this usage counter.
sortOrder:
type: integer
description: The display order for this usage counter.
format: int32
description: Describes one named usage total displayed in organization billing and activity summaries.
BillableUnit:
enum:
- lead_received
- phone_identity_lookup
- sms_segment
- mms_message
- email_message
- voice_minute
- phone_number_month
- warmup_sms_segment
- warmup_voice_minute
- website_setup
- openai_operation
- domain_registration
- 10dlc_application
- 10dlc_campaign_month
- payment_processing_fee
- connection_action
- automation_run
type: string
description: Identifies the metered unit used to price Leadping usage, such as a message, call minute, lookup, or phone number.
IdNamePair:
required:
- id
- name
type: object
properties:
id:
type: string
description: Stable unique identifier of the referenced resource.
name:
type: string
description: Human-readable display name of the referenced resource.
description: Provides a compact API reference to another resource using its stable identifier and human-readable display name.
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.
UsageChannel:
enum:
- lead
- sms
- mms
- email
- voice
- phone_number
- warmup
- website
- openai
- domain
- 10dlc
- payment
- connection
- automation
type: string
description: Identifies the messaging, calling, phone-number, lookup, or platform channel that generated billable usage.
PagedResultOfUsageLedgerTableRow:
type: object
properties:
items:
type: array
items:
allOf:
- $ref: '#/components/schemas/UsageLedgerTableRow'
description: Describes usage ledger data used in Leadping API requests and responses.
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.
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