openapi: 3.2.0
info:
  title: Leadping Analytics 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: Analytics
  description: Provides lead, communication, conversion, and organization performance analytics. Use these endpoints to measure activity over time, compare outcomes, and power operational dashboards and reporting workflows.
paths:
  /analytics/my:
    get:
      tags:
      - Analytics
      summary: Get organization lead communication analytics
      description: Returns current-organization analytics for lead communication, including event volume, response metrics, and date-range filtering.
      operationId: Analytics_GetCurrentOrganization
      parameters:
      - name: startAt
        in: query
        description: Optional inclusive start timestamp for the analytics period.
        schema:
          type: string
          format: date-time
      - name: endAt
        in: query
        description: Optional exclusive end timestamp for the analytics period.
        schema:
          type: string
          format: date-time
      - name: days
        in: query
        description: Optional number of recent days to include when explicit timestamps are not supplied.
        schema:
          type:
          - 'null'
          - integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CustomerAnalyticsResponse'
                description: Aggregates an organization's lead performance, response speed, communication usage, automation health, and activation insights.
        '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.
        '403':
          description: The authenticated user or organization does not have permission to perform this operation.
          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.
        '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:
    CustomerActivationHealthItem:
      type: object
      properties:
        key:
          type: string
          description: Key associated with this Leadping customer activation health item.
        label:
          type: string
          description: Human-readable label for this Leadping customer activation health item.
        status:
          type: string
          description: Current status for this Leadping customer activation health item.
        detail:
          type: string
          description: Human-readable detail for this Leadping customer activation health item.
        actionHref:
          type:
          - 'null'
          - string
          description: Relative URL for the recommended follow-up action.
      description: Describes the state, severity, and recommended next action for one organization activation requirement.
    CustomerAnalyticsResponse:
      type: object
      properties:
        range:
          allOf:
          - $ref: '#/components/schemas/AnalyticsDateRange'
          description: Range associated with this Leadping customer analytics.
        summary:
          allOf:
          - $ref: '#/components/schemas/CustomerAnalyticsSummary'
          description: Human-readable summary for this Leadping customer analytics.
        leadTrend:
          allOf:
          - $ref: '#/components/schemas/CustomerLeadTrend'
          description: Lead trend associated with this Leadping customer analytics.
        responseMetrics:
          allOf:
          - $ref: '#/components/schemas/CustomerResponseMetrics'
          description: Response metrics associated with this Leadping customer analytics.
        communicationUsage:
          allOf:
          - $ref: '#/components/schemas/CustomerCommunicationUsage'
          description: Communication usage associated with this Leadping customer analytics.
        leadSources:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CustomerLeadSourceBreakdown'
            description: Attributes an organization's lead volume, qualification, and conversion outcomes to a specific acquisition source.
          description: Collection of lead sources included with this Leadping customer analytics.
        automationHealth:
          allOf:
          - $ref: '#/components/schemas/CustomerAutomationHealth'
          description: Automation health associated with this Leadping customer analytics.
        activationHealth:
          allOf:
          - $ref: '#/components/schemas/CustomerActivationHealth'
          description: Activation health associated with this Leadping customer analytics.
        needsAttention:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CustomerNeedsAttentionItem'
            description: Identifies an organization-level issue or opportunity and provides severity, supporting context, and a recommended action.
          description: Date and time when this Leadping customer analytics was needs attention.
        generatedAt:
          type: string
          description: Date and time when this Leadping customer analytics was generated.
          format: date-time
      description: Aggregates an organization's lead performance, response speed, communication usage, automation health, and activation insights.
    CustomerResponseMetrics:
      type: object
      properties:
        averageMinutes:
          type:
          - 'null'
          - number
          description: Average minutes measured in minutes.
          format: double
        medianMinutes:
          type:
          - 'null'
          - number
          description: Median minutes measured in minutes.
          format: double
        respondedWithinFiveMinutesPercent:
          type: number
          description: Responded within five minutes percent expressed as a percentage.
          format: double
        respondedLeads:
          type: integer
          description: Number of responded leads represented by this Leadping customer response metrics.
          format: int32
        unrespondedLeads:
          type: integer
          description: Number of unresponded leads represented by this Leadping customer response metrics.
          format: int32
        unreadMessages:
          type: integer
          description: Number of unread messages represented by this Leadping customer response metrics.
          format: int32
        missedCalls:
          type: integer
          description: Number of calls missed during the reporting period.
          format: int32
        averageMinutesTrend:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/AnalyticsTrendPointOfdecimal'
            description: Associates a typed analytics value with one normalized time bucket in a trend series.
          description: Collection of average minutes trend included with this Leadping customer response metrics.
      description: Measures how quickly and consistently an organization responds to leads across supported communication channels.
    AnalyticsTrendPointOfdecimal:
      type: object
      properties:
        startAt:
          type: string
          description: Date and time when this Leadping analytics trend point was start.
          format: date-time
        endAt:
          type: string
          description: Date and time when this Leadping analytics trend point was end.
          format: date-time
        label:
          type: string
          description: Human-readable label for this Leadping analytics trend point.
        value:
          type: number
          description: Value associated with this Leadping analytics trend point.
          format: double
      description: Associates a typed analytics value with one normalized time bucket in a trend series.
    CustomerFailingAutomation:
      type: object
      properties:
        automationId:
          type:
          - 'null'
          - string
          description: Unique identifier of the automation associated with this Leadping customer failing automation.
        name:
          type: string
          description: Human-readable name of the customer failing automation.
        failedAt:
          type:
          - 'null'
          - string
          description: Date and time when the customer failing automation failed.
          format: date-time
        error:
          type:
          - 'null'
          - string
          description: Error associated with this Leadping customer failing automation.
      description: Identifies an automation with recent execution failures and summarizes its affected leads and failure context.
    CustomerLeadSourceBreakdown:
      type: object
      properties:
        source:
          type: string
          description: Source classification for this Leadping customer lead source breakdown.
        leads:
          type: integer
          description: Number of leads represented by this Leadping customer lead source breakdown.
          format: int32
        percent:
          type: number
          description: Percent expressed as a percentage.
          format: double
      description: Attributes an organization's lead volume, qualification, and conversion outcomes to a specific acquisition source.
    CustomerCommunicationUsage:
      type: object
      properties:
        smsSent:
          type: integer
          description: Number of SMS messages sent during the reporting period.
          format: int32
        smsReceived:
          type: integer
          description: Number of SMS messages received during the reporting period.
          format: int32
        failedOrBlockedSms:
          type: integer
          description: Number of SMS messages that failed or were blocked during the reporting period.
          format: int32
        callsPlaced:
          type: integer
          description: Number of outbound calls placed during the reporting period.
          format: int32
        callsReceived:
          type: integer
          description: Number of inbound calls received during the reporting period.
          format: int32
        answeredCalls:
          type: integer
          description: Number of calls answered during the reporting period.
          format: int32
        missedCalls:
          type: integer
          description: Number of calls missed during the reporting period.
          format: int32
        callMinutes:
          type: number
          description: Total connected call duration, in minutes, during the reporting period.
          format: double
        usageSpend:
          type: number
          description: Usage spend represented by this Leadping customer communication usage.
          format: double
        trend:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CustomerCommunicationUsagePoint'
            description: Measures organization messaging and calling activity within one analytics time bucket.
          description: Collection of trend included with this Leadping customer communication usage.
      description: Aggregates an organization's SMS, MMS, and calling activity, delivery outcomes, and billable usage over time.
    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
    CustomerCommunicationUsagePoint:
      type: object
      properties:
        startAt:
          type: string
          description: Date and time when this Leadping customer communication usage point was start.
          format: date-time
        endAt:
          type: string
          description: Date and time when this Leadping customer communication usage point was end.
          format: date-time
        label:
          type: string
          description: Human-readable label for this Leadping customer communication usage point.
        smsSent:
          type: integer
          description: Number of SMS messages sent during the reporting period.
          format: int32
        smsReceived:
          type: integer
          description: Number of SMS messages received during the reporting period.
          format: int32
        calls:
          type: integer
          description: Number of calls represented by this Leadping customer communication usage point.
          format: int32
        callMinutes:
          type: number
          description: Total connected call duration, in minutes, during the reporting period.
          format: double
        spend:
          type: number
          description: Spend represented by this Leadping customer communication usage point.
          format: double
      description: Measures organization messaging and calling activity within one analytics time bucket.
    CustomerAutomationHealth:
      type: object
      properties:
        automationCount:
          type: integer
          description: Total number of automation records represented by this Leadping customer automation health.
          format: int32
        enabledCount:
          type: integer
          description: Total number of enabled records represented by this Leadping customer automation health.
          format: int32
        executions:
          type: integer
          description: Number of executions represented by this Leadping customer automation health.
          format: int32
        successCount:
          type: integer
          description: Total number of success records represented by this Leadping customer automation health.
          format: int32
        failureCount:
          type: integer
          description: Total number of failure records represented by this Leadping customer automation health.
          format: int32
        lastFailure:
          type:
          - 'null'
          - object
          allOf:
          - $ref: '#/components/schemas/CustomerFailingAutomation'
          description: Last failure associated with this Leadping customer automation health.
        failingAutomations:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CustomerFailingAutomation'
            description: Identifies an automation with recent execution failures and summarizes its affected leads and failure context.
          description: Collection of failing automations included with this Leadping customer automation health.
      description: Summarizes automation coverage, execution success, failures, and workflows requiring organization attention.
    CustomerActivationHealth:
      type: object
      properties:
        overallStatus:
          type: string
          description: Current overall status for this Leadping customer activation health.
        items:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CustomerActivationHealthItem'
            description: Describes the state, severity, and recommended next action for one organization activation requirement.
          description: Collection of items included with this Leadping customer activation health.
      description: Summarizes an organization's progress and blockers across onboarding, billing, telephony, compliance, and launch readiness.
    CustomerNeedsAttentionItem:
      type: object
      properties:
        severity:
          type: string
          description: Severity associated with this Leadping customer needs attention item.
        title:
          type: string
          description: Human-readable title for this Leadping customer needs attention item.
        detail:
          type: string
          description: Human-readable detail for this Leadping customer needs attention item.
        actionHref:
          type:
          - 'null'
          - string
          description: Relative URL for the recommended follow-up action.
        actionText:
          type:
          - 'null'
          - string
          description: Action text associated with this Leadping customer needs attention item.
      description: Identifies an organization-level issue or opportunity and provides severity, supporting context, and a recommended action.
    AnalyticsDateRange:
      type: object
      properties:
        startAt:
          type: string
          description: Date and time when this Leadping analytics date range was start.
          format: date-time
        endAt:
          type: string
          description: Date and time when this Leadping analytics date range was end.
          format: date-time
        bucketSize:
          allOf:
          - $ref: '#/components/schemas/AnalyticsBucketSize'
          description: Bucket size associated with this Leadping analytics date range.
      description: Defines the inclusive reporting window and comparison window used to calculate Leadping analytics.
    AnalyticsBucketSize:
      enum:
      - 3
      - 0
      - 1
      - 2
      type: integer
      description: Selects the time interval used to aggregate points in a Leadping analytics trend series.
      format: int32
    AnalyticsTrendPointOfint:
      type: object
      properties:
        startAt:
          type: string
          description: Date and time when this Leadping analytics trend point was start.
          format: date-time
        endAt:
          type: string
          description: Date and time when this Leadping analytics trend point was end.
          format: date-time
        label:
          type: string
          description: Human-readable label for this Leadping analytics trend point.
        value:
          type: integer
          description: Value associated with this Leadping analytics trend point.
          format: int32
      description: Associates a typed analytics value with one normalized time bucket in a trend series.
    CustomerLeadTrend:
      type: object
      properties:
        total:
          type: integer
          description: Total number of total records represented by this Leadping customer lead trend.
          format: int32
        comparison:
          allOf:
          - $ref: '#/components/schemas/AnalyticsComparison'
          description: Date and time when this Leadping customer lead trend was comparison.
        points:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/AnalyticsTrendPointOfint'
            description: Associates a typed analytics value with one normalized time bucket in a trend series.
          description: Collection of points included with this Leadping customer lead trend.
      description: Measures lead creation, qualification, and conversion activity within one reporting time bucket.
    CustomerAnalyticsSummary:
      type: object
      properties:
        leads:
          type: integer
          description: Number of leads represented by this Leadping customer analytics summary.
          format: int32
        leadsComparison:
          allOf:
          - $ref: '#/components/schemas/AnalyticsComparison'
          description: Date and time when this Leadping customer analytics summary was leads comparison.
        averageResponseMinutes:
          type:
          - 'null'
          - number
          description: Average time, in minutes, before a lead receives a response.
          format: double
        medianResponseMinutes:
          type:
          - 'null'
          - number
          description: Median response minutes measured in minutes.
          format: double
        respondedWithinFiveMinutesPercent:
          type: number
          description: Responded within five minutes percent expressed as a percentage.
          format: double
        missedLeads:
          type: integer
          description: Number of missed leads represented by this Leadping customer analytics summary.
          format: int32
        unreadMessages:
          type: integer
          description: Number of unread messages represented by this Leadping customer analytics summary.
          format: int32
        missedCalls:
          type: integer
          description: Number of calls missed during the reporting period.
          format: int32
        smsSent:
          type: integer
          description: Number of SMS messages sent during the reporting period.
          format: int32
        smsReceived:
          type: integer
          description: Number of SMS messages received during the reporting period.
          format: int32
        callsPlaced:
          type: integer
          description: Number of outbound calls placed during the reporting period.
          format: int32
        callsReceived:
          type: integer
          description: Number of inbound calls received during the reporting period.
          format: int32
        callMinutes:
          type: number
          description: Total connected call duration, in minutes, during the reporting period.
          format: double
        usageSpend:
          type: number
          description: Usage spend represented by this Leadping customer analytics summary.
          format: double
        walletBalance:
          type: number
          description: Wallet balance represented by this Leadping customer analytics summary.
          format: double
        billingStatus:
          type: string
          description: Current billing status for this Leadping customer analytics summary.
        walletStatus:
          type: string
          description: Current wallet status for this Leadping customer analytics summary.
      description: Summarizes an organization's primary lead, response, communication, and conversion KPIs for the selected period.
    AnalyticsComparison:
      type: object
      properties:
        current:
          type: number
          description: Metric value for the current reporting period.
          format: double
        previous:
          type: number
          description: Metric value for the preceding comparison period.
          format: double
        changePercent:
          type:
          - 'null'
          - number
          description: Percentage change between the current and previous reporting periods.
          format: double
        direction:
          type: string
          description: Direction classification for this Leadping analytics comparison.
      description: Compares a metric with the preceding period and reports its absolute and percentage change.
  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