Leadping Events API

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:
    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.
    MessageMediaAttachment:
      type: object
      properties:
        url:
          type: string
          description: URL from which the media attachment can be retrieved.
          format: uri
        contentType:
          type:
          - 'null'
          - string
          description: MIME content type of the media attachment.
        size:
          type:
          - 'null'
          - integer
          description: Size of the media attachment in bytes.
          format: int64
        sha256:
          type:
          - 'null'
          - string
          description: SHA-256 digest of the media content, when available.
        fileName:
          type:
          - 'null'
          - string
          description: Original file name of the media attachment, when available.
      description: Media attached to an SMS/MMS conversation event.
    CreateNoteRequest:
      required:
      - text
      type: object
      properties:
        text:
          type: string
          description: Plain-text note content to add to the conversation timeline.
      description: Defines the input used for create note.
    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 identi

# --- 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