openapi: 3.2.0
info:
  title: Leadping User Data Exports 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: UserDataExports
  description: Creates and delivers user-requested exports of Leadping account data. Use these endpoints to request an export, monitor its preparation status, and download the completed archive through a time-limited redirect.
paths:
  /reports/exports/my:
    post:
      tags:
      - UserDataExports
      summary: Request a current-user data export report
      description: Requests a data export for the current user, starting asynchronous report generation for account, lead, and event records.
      operationId: UserDataExports_RequestCurrentUser
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/UserDataExportResponse'
                description: Describes the lifecycle, scope, progress, retention, and downloadable artifacts of a Leadping user-data export request.
        '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: []
  /reports/exports/{exportId}:
    get:
      tags:
      - UserDataExports
      summary: Get a current-user data export report
      description: Returns the status and metadata for one current-user data export, including readiness, expiration, and download availability.
      operationId: UserDataExports_GetCurrentUserExport
      parameters:
      - name: exportId
        in: path
        description: The unique identifier of the current user's data export.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/UserDataExportResponse'
                description: Describes the lifecycle, scope, progress, retention, and downloadable artifacts of a Leadping user-data export request.
        '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: []
  /reports/exports/{exportId}/download:
    get:
      tags:
      - UserDataExports
      summary: Download a current-user data export report
      description: Validates an export download token and redirects to the generated file when the current-user report is ready.
      operationId: UserDataExports_Download
      parameters:
      - name: exportId
        in: path
        description: The unique identifier of the data export to download.
        required: true
        schema:
          type: string
      - name: token
        in: query
        description: The short-lived download token issued for this export.
        schema:
          type: string
      responses:
        '302':
          description: Found
        '404':
          description: The requested resource was not found.
          content:
            text/plain:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
            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.
            text/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
        '410':
          description: Gone
          content:
            text/plain:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
            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.
            text/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: Too Many Requests
          content:
            text/plain:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProblemDetails'
                description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
            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.
            text/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: []
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
    UserDataExportResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique Leadping identifier for the user data export.
        status:
          allOf:
          - $ref: '#/components/schemas/UserDataExportStatuses'
          description: Current status for this Leadping user data export.
        requestedAt:
          type: string
          description: Date and time when the user data export was requested.
          format: date-time
        startedAt:
          type:
          - 'null'
          - string
          description: Date and time when the user data export started.
          format: date-time
        completedAt:
          type:
          - 'null'
          - string
          description: Date and time when the user data export completed.
          format: date-time
        failedAt:
          type:
          - 'null'
          - string
          description: Date and time when the user data export failed.
          format: date-time
        expiresAt:
          type: string
          description: Date and time when the user data export expires.
          format: date-time
        message:
          type:
          - 'null'
          - string
          description: Human-readable message for this Leadping user data export.
        downloadUrl:
          type:
          - 'null'
          - string
          description: Temporary URL for downloading the completed Leadping data export.
          format: uri
        fileName:
          type:
          - 'null'
          - string
          description: Human-readable file name associated with this Leadping user data export.
        contentType:
          type:
          - 'null'
          - string
          description: Media type of the generated file or response content.
        sizeBytes:
          type:
          - 'null'
          - integer
          description: Size of the generated export archive in bytes, when the export is ready.
          format: int64
        downloadCount:
          type: integer
          description: Total number of download records represented by this Leadping user data export.
          format: int32
        maxDownloadCount:
          type: integer
          description: Total number of max download records represented by this Leadping user data export.
          format: int32
        files:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/UserDataExportFile'
            description: Describes a file included in a user-data export, including its logical category, media type, size, and integrity metadata.
          description: Collection of files included with this Leadping user data export.
      description: Describes the lifecycle, scope, progress, retention, and downloadable artifacts of a Leadping user-data export request.
    UserDataExportStatuses:
      enum:
      - Pending
      - Processing
      - Completed
      - Failed
      - Expired
      type: string
      description: Identifies the preparation, availability, failure, expiration, or deletion stage of a Leadping user-data export.
    UserDataExportFile:
      type: object
      properties:
        category:
          type: string
          description: Category classification for this Leadping user data export file.
        fileName:
          type: string
          description: Human-readable file name associated with this Leadping user data export file.
        contentType:
          type: string
          description: Media type of the generated file or response content.
        rowCount:
          type: integer
          description: Total number of row records represented by this Leadping user data export file.
          format: int32
      description: Describes a file included in a user-data export, including its logical category, media type, size, and integrity metadata.
  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