openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Bulk Phone Number Campaigns API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Phone number campaign bulk assignment
  name: Bulk Phone Number Campaigns
paths:
  /10dlc/phoneNumberAssignmentByProfile:
    post:
      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`.
      operationId: PostAssignMessagingProfileToCampaign
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignProfileToCampaignRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignProfileToCampaignResponse'
          description: Successful Response
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsDataErrorMessage'
          description: Error searching for phone numbers
      summary: Assign Messaging Profile To Campaign
      tags:
      - Bulk Phone Number Campaigns
      x-latency-category: responsive
  /10dlc/phoneNumberAssignmentByProfile/{taskId}:
    get:
      description: Check the status of the task associated with assigning all phone numbers on a messaging profile to a campaign by `taskId`.
      operationId: GetAssignmentTaskStatus
      parameters:
      - in: path
        name: taskId
        required: true
        schema:
          title: Taskid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentTaskStatusResponse'
          description: Successful Response
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
      summary: Get Assignment Task Status
      tags:
      - Bulk Phone Number Campaigns
      x-latency-category: responsive
  /10dlc/phoneNumberAssignmentByProfile/{taskId}/phoneNumbers:
    get:
      description: Check the status of the individual phone number/campaign assignments associated with the supplied `taskId`.
      operationId: GetPhoneNumberStatus
      parameters:
      - in: path
        name: taskId
        required: true
        schema:
          title: Taskid
          type: string
      - in: query
        name: recordsPerPage
        required: false
        schema:
          default: 20
          title: Recordsperpage
          type: integer
      - in: query
        name: page
        required: false
        schema:
          default: 1
          title: Page
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberStatusResponsePaginated'
          description: Successful Response
        '422':
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
      summary: Get Phone Number Status
      tags:
      - Bulk Phone Number Campaigns
      x-latency-category: responsive
components:
  schemas:
    AssignProfileToCampaignResponse:
      properties:
        campaignId:
          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
          title: Campaignid
          type: string
        messagingProfileId:
          description: The ID of the messaging profile that you want to link to the specified campaign.
          example: 4001767e-ce0f-4cae-9d5f-0d5e636e7809
          title: Messagingprofileid
          type: string
        taskId:
          description: The ID of the task associated with assigning a messaging profile to a campaign.
          example: 667a80f8-b0a9-49d0-b9ab-a7a1bcc45086
          title: Taskid
          type: string
        tcrCampaignId:
          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
          title: Tcrcampaignid
          type: string
      required:
      - messagingProfileId
      - taskId
      title: AssignProfileToCampaignResponse
      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
    10dlc_TaskStatus:
      description: An enumeration.
      enum:
      - pending
      - processing
      - completed
      - failed
      title: TaskStatus
      type: string
    ProfileAssignmentPhoneNumbers:
      properties:
        phoneNumber:
          description: The phone number that the status is being checked for.
          example: '+12024567890'
          title: Phonenumber
          type: string
        status:
          description: The status of the associated phone number assignment.
          example: pending
          title: Status
          type: string
        taskId:
          description: The ID of the task associated with the phone number.
          example: 667a80f8-b0a9-49d0-b9ab-a7a1bcc45086
          title: Taskid
          type: string
      required:
      - taskId
      - phoneNumber
      - status
      title: ProfileAssignmentPhoneNumbers
      type: object
    10dlc_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/10dlc_Error'
          type: array
      type: object
    SettingsDataErrorMessage:
      properties:
        message:
          title: Message
          type: string
      required:
      - message
      title: SettingsDataErrorMessage
      type: object
    AssignProfileToCampaignRequest:
      properties:
        campaignId:
          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
          title: Campaignid
          type: string
        messagingProfileId:
          description: The ID of the messaging profile that you want to link to the specified campaign.
          example: 4001767e-ce0f-4cae-9d5f-0d5e636e7809
          title: Messagingprofileid
          type: string
        tcrCampaignId:
          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
          title: Tcrcampaignid
          type: string
      required:
      - messagingProfileId
      title: AssignProfileToCampaignRequest
      type: object
    AssignmentTaskStatusResponse:
      properties:
        createdAt:
          format: date-time
          title: Createdat
          type: string
        status:
          allOf:
          - $ref: '#/components/schemas/10dlc_TaskStatus'
          description: The status of the task associated with assigning a messaging profile to a campaign.
          example: pending
          type: string
        taskId:
          title: Taskid
          type: string
        updatedAt:
          format: date-time
          title: Updatedat
          type: string
      required:
      - taskId
      - status
      title: AssignmentTaskStatusResponse
      type: object
    PhoneNumberStatusResponsePaginated:
      properties:
        records:
          items:
            $ref: '#/components/schemas/ProfileAssignmentPhoneNumbers'
          title: Records
          type: array
      required:
      - records
      title: PhoneNumberStatusResponsePaginated
      type: object
  responses:
    10dlc_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/10dlc_Errors'
      description: Generic response error
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http