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