openapi: 3.2.0
info:
title: Leadping 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: Events
description: Provides a unified record of Leadping activity across communication channels. Use these endpoints to retrieve event timelines, search event history, inspect event details, and record supported application events.
paths:
/events/all/my:
post:
tags:
- Events
summary: List current-user lead events
description: Lists event records visible to the current user with paging, sorting, and filters across lead, SMS, call, and automation events.
operationId: Events_GetAllForCurrentUser
parameters:
- name: category
in: query
description: Optional event category used to narrow the results.
schema:
type: string
- name: startAt
in: query
description: Optional inclusive start timestamp for event occurrence.
schema:
type: string
format: date-time
- name: endAt
in: query
description: Optional exclusive end timestamp for event occurrence.
schema:
type: string
format: date-time
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: Events were successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfEventTableRow'
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/organizations/{organizationId}:
post:
tags:
- Events
summary: List organization lead event history
description: Lists event records for an organization with paging and filters so admins can review lead communication and automation events.
operationId: Events_GetAllForOrganization
parameters:
- name: organizationId
in: path
description: The organization identifier.
required: true
schema:
type: string
- name: startAt
in: query
description: Optional inclusive start timestamp for event occurrence.
schema:
type: string
format: date-time
- name: endAt
in: query
description: Optional exclusive end timestamp for event occurrence.
schema:
type: string
format: date-time
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 event table row.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfEventTableRow'
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/conversations/{conversationId}:
post:
tags:
- Events
summary: List a conversation's event history
description: Lists event records for one conversation with paging, including notes, messages, calls, and follow-up history.
operationId: Events_GetAllForConversation
parameters:
- name: conversationId
in: path
description: The ID of the conversation.
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: Events for the conversation were successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfEventTableRow'
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/leads/{leadId}:
post:
tags:
- Events
summary: List event history for a lead
description: Lists event records for one lead with paging, covering communication, routing, automation, and event changes.
operationId: Events_GetAllForLead
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: Events for the lead were successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PagedResultOfEventTableRow'
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/{eventId}:
get:
tags:
- Events
summary: Get lead event details by ID
description: Returns one event record by ID, including event type, timestamps, related entities, and summary payload data.
operationId: Events_GetById
parameters:
- name: eventId
in: path
description: The ID of the event.
required: true
schema:
type: string
responses:
'200':
description: Event was successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EventTableRow'
description: Summarizes event timeline data in paginated and searchable results.
'404':
description: Event 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/detail/{eventId}:
get:
tags:
- Events
summary: Get full lead event payload by ID
description: Returns detailed event data by ID, including the full JSON payload for debugging, audit review, and workflow inspection.
operationId: Events_GetDetailById
parameters:
- name: eventId
in: path
description: The ID of the event.
required: true
schema:
type: string
responses:
'200':
description: Event details were successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EventDetailResponse'
description: Describes event detail data returned by Leadping.
'404':
description: Event 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/conversations/{conversationId}/notes:
post:
tags:
- Events
summary: Add a note to a conversation
description: Creates a note event on a conversation so users can document lead context, handoffs, and follow-up details.
operationId: Events_CreateNote
parameters:
- name: conversationId
in: path
description: The conversation identifier.
required: true
schema:
type: string
requestBody:
description: The create note request payload for the operation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CreateNoteRequest'
description: Defines the input used for create note.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/CreateNoteRequest'
description: Defines the input used for create note.
required: true
responses:
'200':
description: Returns the event table row.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EventTableRow'
description: Summarizes event timeline data in paginated and searchable results.
'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:
PagedResultOfEventTableRow:
type: object
properties:
items:
type: array
items:
allOf:
- $ref: '#/components/schemas/EventTableRow'
description: Summarizes event timeline 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.
EventDetailResponse:
type: object
properties:
eventType:
type: string
description: Event type used to classify this timeline, SMS, call, or automation event.
secondaryEventType:
type:
- 'null'
- string
description: Secondary event type used for additional event classification.
description:
type:
- 'null'
- string
description: Human-readable description that explains this event detail response to API users.
eventCategory:
type:
- 'null'
- string
description: High-level category used to group this Leadping event.
timelineType:
enum:
- Message
- Sms
- Mms
- Call
- Voicemail
- Note
- LeadStatusChange
- LeadCreated
- LeadUpdated
- Notification
- Payment
- Warmup
type:
- 'null'
- string
description: Classifies the kind of activity displayed in a lead or conversation event timeline.
timelineCategory:
type:
- 'null'
- string
description: Timeline category used to group events for display and filtering.
conversationId:
type:
- 'null'
- string
description: Conversation ID that links this event detail response to the Leadping inbox thread.
summary:
type:
- 'null'
- string
description: Short human-readable summary of this event detail response for lists, timelines, and notifications.
direction:
type:
- 'null'
- string
description: Communication direction for this event detail response, such as inbound or outbound.
status:
enum:
- Pending
- InProgress
- Completed
- Failed
- Cancelled
type:
- 'null'
- string
description: Describes whether a Leadping event is pending, processing, completed, failed, or otherwise resolved.
statusReason:
type:
- 'null'
- string
description: Human-readable reason explaining the current status of this event detail response.
fromPhoneNumberId:
type:
- 'null'
- string
description: Sender phone number ID used for this outbound SMS or call.
outboundPhoneNumberId:
type:
- 'null'
- string
description: Phone number ID selected for outbound delivery.
fromPhoneNumber:
type:
- 'null'
- string
description: Sender phone number used for this communication.
toPhoneNumber:
type:
- 'null'
- string
description: Recipient phone number used for this communication.
queuedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping queued this event detail response for processing.
format: date-time
scheduledFor:
type:
- 'null'
- string
description: UTC timestamp when the related delivery or workflow action is scheduled to run.
format: date-time
sendingStartedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping began sending this message.
format: date-time
sentAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping sent this message to the provider.
format: date-time
deliveredAt:
type:
- 'null'
- string
description: UTC timestamp when the provider confirmed delivery.
format: date-time
receivedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping received this inbound event or message.
format: date-time
failedAt:
type:
- 'null'
- string
description: UTC timestamp when processing failed for this event detail response.
format: date-time
undeliverableAt:
type:
- 'null'
- string
description: UTC timestamp when the provider marked the message undeliverable.
format: date-time
blockedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping blocked this communication.
format: date-time
canceledAt:
type:
- 'null'
- string
description: UTC timestamp when this delivery or workflow was canceled.
format: date-time
user:
type:
- 'null'
- object
allOf:
- $ref: '#/components/schemas/IdNamePair'
description: User summary connected to this event detail response.
userEmail:
type:
- 'null'
- string
description: Email address for the user connected to this event detail response.
format: email
userId:
type: string
description: User ID associated with the activity that created this event.
leadId:
type:
- 'null'
- string
description: Lead ID associated with this event detail record.
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 event detail data returned by Leadping.
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'
-
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leadping/refs/heads/main/openapi/leadping-events-api-openapi.yml