openapi: 3.2.0
info:
  title: Leadping Suppressions 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: Suppressions
  description: Manages recipient suppression state for compliant Leadping communication workflows. Use these endpoints to check contact eligibility, record or release suppressions, and review suppression history before sending messages or placing calls.
paths:
  /suppressions:
    post:
      tags:
      - Suppressions
      summary: Create or reactivate a recipient suppression
      description: Creates or reactivates a Leadping suppression entry that blocks future outreach to a recipient across the selected communication channel.
      operationId: Suppressions_Suppress
      requestBody:
        description: The suppression entry request payload for the operation.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SuppressionEntryRequest'
              description: Defines a recipient and communication channel to suppress, release, or check before Leadping sends outreach.
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SuppressionEntryRequest'
              description: Defines a recipient and communication channel to suppress, release, or check before Leadping sends outreach.
        required: true
      responses:
        '201':
          description: The suppression entry response was created successfully.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuppressionEntryResponse'
                description: Describes a recipient suppression that prevents outreach through one or more communication channels.
        '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: []
  /suppressions/release:
    post:
      tags:
      - Suppressions
      summary: Release an active recipient suppression
      description: Releases an active Leadping suppression entry so a recipient can be contacted again, returning the updated suppression record when available.
      operationId: Suppressions_Release
      requestBody:
        description: The suppression entry request payload for the operation.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SuppressionEntryRequest'
              description: Defines a recipient and communication channel to suppress, release, or check before Leadping sends outreach.
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SuppressionEntryRequest'
              description: Defines a recipient and communication channel to suppress, release, or check before Leadping sends outreach.
        required: true
      responses:
        '200':
          description: Returns the suppression entry response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuppressionEntryResponse'
                description: Describes a recipient suppression that prevents outreach through one or more communication channels.
        '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: []
  /suppressions/check:
    post:
      tags:
      - Suppressions
      summary: Check whether a recipient is suppressed
      description: Checks whether a recipient is blocked by an active Leadping suppression entry before sending messages or placing calls through the selected channel.
      operationId: Suppressions_Check
      requestBody:
        description: The suppression entry request payload for the operation.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SuppressionEntryRequest'
              description: Defines a recipient and communication channel to suppress, release, or check before Leadping sends outreach.
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SuppressionEntryRequest'
              description: Defines a recipient and communication channel to suppress, release, or check before Leadping sends outreach.
        required: true
      responses:
        '200':
          description: Returns the suppression check result.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuppressionCheckResult'
                description: Reports whether Leadping may contact a recipient and identifies the active suppression when contact is blocked.
        '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: []
  /suppressions/all/my:
    post:
      tags:
      - Suppressions
      summary: List current-organization suppression entries
      description: Returns a filtered, paginated list of recipients the current organization has blocked from phone, SMS, or email outreach.
      operationId: Suppressions_GetAllForCurrentOrganization
      requestBody:
        description: Pagination, filtering, and sorting options for suppression entries.
        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: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PagedResultOfSuppressionEntryResponse'
                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: []
  /suppressions/{id}:
    get:
      tags:
      - Suppressions
      summary: Get an organization suppression entry
      description: Returns one suppression entry for the current organization, including its recipient, channel, reason, status, and audit timestamps.
      operationId: Suppressions_Get
      parameters:
      - name: id
        in: path
        description: The unique identifier of the suppression entry to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuppressionEntryResponse'
                description: Describes a recipient suppression that prevents outreach through one or more communication channels.
        '404':
          description: The requested resource 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: []
components:
  schemas:
    PagedResultOfSuppressionEntryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/SuppressionEntryResponse'
            description: Describes a recipient suppression that prevents outreach through one or more communication channels.
          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.
    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.
    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
    SuppressionEntryAudit:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this suppression audit record.
        status:
          type: string
          description: Suppression status established by this change, such as active or released.
        source:
          type: string
          description: System or workflow that initiated the change.
        timestamp:
          type: string
          description: UTC timestamp when the suppression change occurred.
          format: date-time
        actorId:
          type:
          - 'null'
          - string
          description: Identifier of the user or system actor responsible for the change.
        reason:
          type:
          - 'null'
          - string
          description: Human-readable reason recorded for the suppression change.
        safeMetadata:
          type: object
          additionalProperties:
            type: string
          description: Non-sensitive metadata that provides additional audit context.
      description: Records one auditable change to a recipient suppression entry.
    SuppressionEntryResponse:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
          description: Unique Leadping identifier for the suppression entry.
        organizationId:
          type:
          - 'null'
          - string
          description: Identifier of the organization that owns the suppression entry.
        recipientIdentifier:
          type:
          - 'null'
          - string
          description: Provider or customer identifier used to recognize the suppressed recipient.
        normalizedPhoneNumber:
          type:
          - 'null'
          - string
          description: Suppressed phone number normalized to a consistent format.
        normalizedEmail:
          type:
          - 'null'
          - string
          description: Suppressed email address normalized for matching.
          format: email
        channel:
          type:
          - 'null'
          - string
          description: Communication channel affected by the suppression, such as SMS, voice, email, or all channels.
        source:
          type:
          - 'null'
          - string
          description: System or workflow that created the suppression.
        status:
          type:
          - 'null'
          - string
          description: Current lifecycle state, such as active or released.
        reason:
          type:
          - 'null'
          - string
          description: Human-readable reason the recipient was suppressed or subsequently released.
        suppressedAt:
          type:
          - 'null'
          - string
          description: UTC timestamp when the suppression became active.
          format: date-time
        releasedAt:
          type:
          - 'null'
          - string
          description: UTC timestamp when the suppression was released, or null while it remains active.
          format: date-time
        audit:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/SuppressionEntryAudit'
            description: Records one auditable change to a recipient suppression entry.
          description: Chronological audit history of suppression and release changes.
      description: Describes a recipient suppression that prevents outreach through one or more communication channels.
    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.
    SuppressionCheckResult:
      type: object
      properties:
        allowed:
          type: boolean
          description: Whether outreach to the recipient is allowed for the requested channel.
        organizationId:
          type:
          - 'null'
          - string
          description: Identifier of the organization whose suppression list was checked.
        recipientIdentifier:
          type:
          - 'null'
          - string
          description: Provider or customer identifier used to match the recipient.
        normalizedPhoneNumber:
          type:
          - 'null'
          - string
          description: Phone number used for matching, normalized to a consistent format.
        normalizedEmail:
          type:
          - 'null'
          - string
          description: Email address used for matching, normalized for comparison.
          format: email
        channel:
          type:
          - 'null'
          - string
          description: Communication channel evaluated by the suppression check.
        suppressionEntryId:
          type:
          - 'null'
          - string
          description: Identifier of the active suppression that blocked contact, when one matched.
        source:
          type:
          - 'null'
          - string
          description: The source value on the active suppression entry that blocked this check.
        suppressedAt:
          type:
          - 'null'
          - string
          description: The date and time the blocking suppression became active.
          format: date-time
        customerReason:
          type:
          - 'null'
          - string
          description: Customer-safe explanation of why contact is blocked or allowed.
      description: Reports whether Leadping may contact a recipient and identifies the active suppression when contact is blocked.
    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.
    SuppressionEntryRequest:
      required:
      - organizationId
      type: object
      properties:
        organizationId:
          type: string
          description: Organization whose suppression list should be used.
        recipientIdentifier:
          type:
          - 'null'
          - string
          description: Optional provider or customer identifier that uniquely identifies the recipient.
        phoneNumber:
          type:
          - 'null'
          - string
          description: Recipient phone number to suppress or check, preferably in E.164 format.
        email:
          type:
          - 'null'
          - string
          description: Recipient email address to suppress or check.
          format: email
        channel:
          type: string
          description: Communication channel affected by the suppression, such as SMS, voice, email, or all channels.
        reason:
          type:
          - 'null'
          - string
          description: Human-readable reason for creating or releasing the suppression.
      description: Defines a recipient and communication channel to suppress, release, or check before Leadping sends outreach.
    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