openapi: 3.2.0
info:
  title: Leadping Wallets 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: Wallets
  description: Manages organization wallet balances, funding, and credit activity. Use these endpoints to inspect wallet state and history, configure wallet behavior, add funds, and record credits or adjustments.
paths:
  /wallets/{id}:
    get:
      tags:
      - Wallets
      summary: Get an organization wallet balance by ID
      description: Returns one wallet by ID, including balance, billing context, and funding status for account payment workflows.
      operationId: Wallets_Get
      parameters:
      - name: id
        in: path
        description: The ID of the wallet to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Wallet was successfully retrieved.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletResponse'
                description: Describes billing wallet data returned by Leadping.
        '404':
          description: The specified wallet 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.
        '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: []
  /wallets/me:
    get:
      tags:
      - Wallets
      summary: Get the current organization wallet balance
      description: Returns the current organization wallet, including balance and funding status used for communication delivery and billing.
      operationId: Wallets_GetForCurrentOrganization
      responses:
        '200':
          description: Wallet was successfully retrieved.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletResponse'
                description: Describes billing wallet data returned by Leadping.
        '404':
          description: The current organization wallet 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.
        '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: []
components:
  schemas:
    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
    WalletResponse:
      type: object
      properties:
        balance:
          type:
          - 'null'
          - number
          description: Wallet or account balance after this transaction is applied.
          format: double
        balanceCalculatedAt:
          type:
          - 'null'
          - string
          description: UTC timestamp when Leadping last calculated the wallet balance.
          format: date-time
        amountPurchased:
          type:
          - 'null'
          - number
          description: Amount of wallet credit purchased in this deposit.
          format: double
        amountRemaining:
          type:
          - 'null'
          - number
          description: Amount of wallet credit still available for future usage.
          format: double
        currency:
          type:
          - 'null'
          - string
          description: ISO currency code used for the monetary amounts in this billing wallet response.
        purchasedAt:
          type:
          - 'null'
          - string
          description: UTC timestamp when the wallet credit was purchased.
          format: date-time
        expiresAt:
          type:
          - 'null'
          - string
          description: UTC timestamp when the wallet credit expires.
          format: date-time
        sourceType:
          enum:
          - purchase
          - promo
          - admin_adjustment
          - refund_adjustment
          - chargeback_reversal
          - compromise_restoration
          type:
          - 'null'
          - string
          description: Defines the source that created a wallet credit lot.
        creditStatus:
          enum:
          - active
          - consumed
          - expired
          - refunded
          - voided
          - disputed
          type:
          - 'null'
          - string
          description: Defines the lifecycle state for a wallet credit lot.
        organizationId:
          type:
          - 'null'
          - string
          description: Organization ID that owns this wallet balance or credit.
        originalTransactionId:
          type:
          - 'null'
          - string
          description: Original wallet transaction ID referenced by a reversal, refund, or adjustment.
        nextCreditExpirationAt:
          type:
          - 'null'
          - string
          description: UTC timestamp when the next wallet credit amount expires.
          format: date-time
        nextExpiringCreditAmount:
          type:
          - 'null'
          - number
          description: Amount of wallet credit scheduled to expire next.
          format: double
        expiredCreditAmount:
          type:
          - 'null'
          - number
          description: Amount of wallet credit that has expired.
          format: double
        name:
          type: string
          description: Human-readable display name of the resource.
        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 billing wallet data returned by Leadping.
  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