Telnyx Bulk Phone Number Campaigns API

openapi: 3.2.0
info:
  title: Telnyx Bulk Phone Number Campaigns API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged Bulk Phone Number Campaigns across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Bulk Phone Number Campaigns
  description: Phone number campaign bulk assignment
paths:
  /10dlc/phoneNumberAssignmentByProfile:
    post:
      tags:
      - Bulk Phone Number Campaigns
      summary: Assign Messaging Profile To Campaign
      operationId: PostAssignMessagingProfileToCampaign
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignProfileToCampaignRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignProfileToCampaignResponse'
        '500':
          description: Error searching for phone numbers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsDataErrorMessage'
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse_ca4eb0ad6f'
      description: This endpoint allows you to link all phone numbers associated with a Messaging Profile to a campaign. **Please note:** if you want to assign phone numbers to a campaign that you did not create with Telnyx 10DLC services, this endpoint allows that provided that you've shared the campaign with Telnyx. In this case, only provide the parameter, `tcrCampaignId`, and not `campaignId`. In all other cases (where the campaign you're assigning was created with Telnyx 10DLC services), only provide `campaignId`, not `tcrCampaignId`.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /10dlc/phoneNumberAssignmentByProfile/{taskId}:
    get:
      tags:
      - Bulk Phone Number Campaigns
      summary: Get Assignment Task Status
      operationId: GetAssignmentTaskStatus
      parameters:
      - required: true
        schema:
          title: Taskid
          type: string
        name: taskId
        in: path
        description: Unique identifier of the task.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentTaskStatusResponse'
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse_ca4eb0ad6f'
      description: Check the status of the task associated with assigning all phone numbers on a messaging profile to a campaign by `taskId`.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /10dlc/phoneNumberAssignmentByProfile/{taskId}/phoneNumbers:
    get:
      tags:
      - Bulk Phone Number Campaigns
      summary: Get Phone Number Status
      operationId: GetPhoneNumberStatus
      parameters:
      - required: true
        schema:
          title: Taskid
          type: string
        name: taskId
        in: path
        description: Unique identifier of the task.
      - required: false
        schema:
          title: Recordsperpage
          default: 20
          type: integer
        name: recordsPerPage
        in: query
        description: Number of records to return per page.
      - required: false
        schema:
          title: Page
          default: 1
          type: integer
        name: page
        in: query
        description: Page number to retrieve (1-based).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberStatusResponsePaginated'
        '422':
          $ref: '#/components/responses/10dlc_GenericErrorResponse_ca4eb0ad6f'
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse_ca4eb0ad6f'
      description: Check the status of the individual phone number/campaign assignments associated with the supplied `taskId`.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  schemas:
    Errors:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/billing-group_Error'
      type: object
    AssignProfileToCampaignRequest:
      title: AssignProfileToCampaignRequest
      required:
      - messagingProfileId
      type: object
      properties:
        messagingProfileId:
          title: Messagingprofileid
          type: string
          description: The ID of the messaging profile that you want to link to the specified campaign.
          example: 4001767e-ce0f-4cae-9d5f-0d5e636e7809
        tcrCampaignId:
          title: Tcrcampaignid
          type: string
          description: The TCR ID of the shared campaign you want to link to the specified messaging profile (for campaigns not created using Telnyx 10DLC services only). If you supply this ID in the request, do not also include a campaignId.
          example: CWZTFH1
        campaignId:
          title: Campaignid
          type: string
          description: The ID of the campaign you want to link to the specified messaging profile. If you supply this ID in the request, do not also include a tcrCampaignId.
          example: 4b300178-131c-d902-d54e-72d90ba1620j
    AssignProfileToCampaignResponse:
      title: AssignProfileToCampaignResponse
      required:
      - messagingProfileId
      - taskId
      type: object
      properties:
        messagingProfileId:
          title: Messagingprofileid
          type: string
          description: The ID of the messaging profile that you want to link to the specified campaign.
          example: 4001767e-ce0f-4cae-9d5f-0d5e636e7809
        tcrCampaignId:
          title: Tcrcampaignid
          type: string
          description: The TCR ID of the shared campaign you want to link to the specified messaging profile (for campaigns not created using Telnyx 10DLC services only). If you supply this ID in the request, do not also include a campaignId.
          example: CWZTFH1
        campaignId:
          title: Campaignid
          type: string
          description: The ID of the campaign you want to link to the specified messaging profile. If you supply this ID in the request, do not also include a tcrCampaignId.
          example: 4b300178-131c-d902-d54e-72d90ba1620j
        taskId:
          title: Taskid
          type: string
          description: The ID of the task associated with assigning a messaging profile to a campaign.
          example: 667a80f8-b0a9-49d0-b9ab-a7a1bcc45086
    ProfileAssignmentPhoneNumbers:
      title: ProfileAssignmentPhoneNumbers
      required:
      - taskId
      - phoneNumber
      - status
      type: object
      properties:
        taskId:
          title: Taskid
          type: string
          description: The ID of the task associated with the phone number.
          example: 667a80f8-b0a9-49d0-b9ab-a7a1bcc45086
        phoneNumber:
          title: Phonenumber
          type: string
          description: The phone number that the status is being checked for.
          example: '+12024567890'
        status:
          title: Status
          type: string
          description: The status of the associated phone number assignment.
          example: pending
    billing-group_Error:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: integer
          format: int32
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
          properties: {}
          additionalProperties: true
    PhoneNumberStatusResponsePaginated:
      title: PhoneNumberStatusResponsePaginated
      required:
      - records
      type: object
      properties:
        records:
          title: Records
          type: array
          items:
            $ref: '#/components/schemas/ProfileAssignmentPhoneNumbers'
    SettingsDataErrorMessage:
      title: SettingsDataErrorMessage
      required:
      - message
      type: object
      properties:
        message:
          title: Message
          type: string
    AssignmentTaskStatusResponse:
      title: AssignmentTaskStatusResponse
      required:
      - taskId
      - status
      type: object
      properties:
        taskId:
          title: Taskid
          type: string
        status:
          allOf:
          - $ref: '#/components/schemas/10dlc_TaskStatus'
          type: string
          description: The status of the task associated with assigning a messaging profile to a campaign.
          example: pending
        createdAt:
          title: Createdat
          type: string
          format: date-time
        updatedAt:
          title: Updatedat
          type: string
          format: date-time
    10dlc_TaskStatus:
      title: TaskStatus
      enum:
      - pending
      - processing
      - completed
      - failed
      type: string
      description: An enumeration.
    10dlc_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/10dlc_Error'
          type: array
      type: object
    10dlc_Error:
      properties:
        code:
          type: string
        detail:
          type: string
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
      type: object
    Errors_2:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      type: object
    Error:
      required:
      - code
      - title
      properties:
        code:
          type: string
          x-format: int64
        title:
          type: string
        detail:
          type: string
          description: A human-readable explanation of the error.
        description:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
              format: json-pointer
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
          additionalProperties: true
      example:
        title: Invalid street address
        source:
          pointer: /street_address
        code: '20207'
        description: The street address provided is invalid.
      type: object
  responses:
    10dlc_GenericErrorResponse_ca4eb0ad6f:
      description: Generic response error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: string
              title: string
              detail: string
              source:
                pointer: string
                parameter: string
    10dlc_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/10dlc_Errors'
      description: Generic response error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt