Telnyx Shared Campaigns API

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 Shared 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:
- name: Shared Campaigns
paths:
  /10dlc/partnerCampaign/sharedByMe:
    get:
      description: 'Get all partner campaigns you have shared to Telnyx in a paginated fashion


        This endpoint is currently limited to only returning shared campaigns that Telnyx

        has accepted. In other words, shared but pending campaigns are currently omitted

        from the response from this endpoint.'
      operationId: GetPartnerCampaignsSharedByUser
      parameters:
      - description: The 1-indexed page number to get. The default value is `1`.
        in: query
        name: page
        required: false
        schema:
          default: 1
          description: The 1-indexed page number to get. The default value is `1`.
          title: Page
          type: integer
      - description: The amount of records per page, limited to between 1 and 500 inclusive. The default value is `10`.
        in: query
        name: recordsPerPage
        required: false
        schema:
          default: 10
          description: The amount of records per page, limited to between 1 and 500 inclusive. The default value is `10`.
          title: Recordsperpage
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedCampaignRecordSet'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
      summary: List shared partner campaigns
      tags:
      - Shared Campaigns
      x-latency-category: responsive
  /10dlc/partnerCampaign/{campaignId}/sharing:
    get:
      operationId: GetPartnerCampaignSharingStatus
      parameters:
      - description: ID of the campaign in question
        in: path
        name: campaignId
        required: true
        schema:
          description: ID of the campaign in question
          title: Campaignid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  $ref: '#/components/schemas/CampaignSharingStatus'
                title: Response Get Sharing Status Public Partnercampaign  Campaignid  Sharing Get
                type: object
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
      summary: Get Sharing Status
      tags:
      - Shared Campaigns
      x-latency-category: responsive
  /10dlc/partner_campaigns:
    get:
      description: 'Retrieve all partner campaigns you have shared to Telnyx in a paginated fashion.


        This endpoint is currently limited to only returning shared campaigns that Telnyx has accepted. In other words, shared but pending campaigns are currently omitted from the response from this endpoint.'
      operationId: GetSharedCampaigns
      parameters:
      - description: The 1-indexed page number to get. The default value is `1`.
        in: query
        name: page
        required: false
        schema:
          default: 1
          description: The 1-indexed page number to get. The default value is `1`.
          title: Page
          type: integer
      - description: The amount of records per page, limited to between 1 and 500 inclusive. The default value is `10`.
        in: query
        name: recordsPerPage
        required: false
        schema:
          default: 10
          description: The amount of records per page, limited to between 1 and 500 inclusive. The default value is `10`.
          title: Recordsperpage
          type: integer
      - description: Specifies the sort order for results. If not given, results are sorted by createdAt in descending order.
        example: -assignedPhoneNumbersCount
        in: query
        name: sort
        required: false
        schema:
          default: -createdAt
          description: Specifies the sort order for results. If not given, results are sorted by created_at in descending order.
          enum:
          - assignedPhoneNumbersCount
          - -assignedPhoneNumbersCount
          - brandDisplayName
          - -brandDisplayName
          - tcrBrandId
          - -tcrBrandId
          - tcrCampaignId
          - -tcrCampaignId
          - createdAt
          - -createdAt
          - campaignStatus
          - -campaignStatus
          title: Sort
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelnyxDownstreamCampaignRecordSet'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
      summary: List Shared Campaigns
      tags:
      - Shared Campaigns
      x-latency-category: responsive
  /10dlc/partner_campaigns/{campaignId}:
    get:
      description: Retrieve campaign details by `campaignId`.
      operationId: GetSharedCampaign
      parameters:
      - in: path
        name: campaignId
        required: true
        schema:
          title: Campaignid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelnyxDownstreamCampaign'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
      summary: Get Single Shared Campaign
      tags:
      - Shared Campaigns
      x-latency-category: responsive
    patch:
      description: Update campaign details by `campaignId`. **Please note:** Only webhook urls are editable.
      operationId: UpdateSharedCampaign
      parameters:
      - in: path
        name: campaignId
        required: true
        schema:
          title: Campaignid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePartnerCampaignRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelnyxDownstreamCampaign'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        4XX:
          $ref: '#/components/responses/10dlc_GenericErrorResponse'
      summary: Update Single Shared Campaign
      tags:
      - Shared Campaigns
      x-latency-category: responsive
components:
  schemas:
    TelnyxDownstreamCampaign:
      description: Campaign is generated by the 10DLC registry once the corresponding campaign request is approved. Each campaign is assigned a unique identifier - **campaignId**. Once a campaign is activated, limited information is published to the NetNumber OSR service for consumption by members of the ecosystem. When a campaign is suspended(reversible) or expired(non-reversible), campaign data is deleted from the OSR service.
      properties:
        ageGated:
          description: Age gated content in campaign.
          title: AgeGated
          type: boolean
        assignedPhoneNumbersCount:
          description: Number of phone numbers associated with the campaign
          example: 3
          title: AssignedPhoneNumbersCount
          type: number
        brandDisplayName:
          description: Display or marketing name of the brand.
          example: ABC Mobile
          title: Branddisplayname
          type: string
        campaignStatus:
          description: Campaign status
          enum:
          - TCR_PENDING
          - TCR_SUSPENDED
          - TCR_EXPIRED
          - TCR_ACCEPTED
          - TCR_FAILED
          - TELNYX_ACCEPTED
          - TELNYX_FAILED
          - MNO_PENDING
          - MNO_ACCEPTED
          - MNO_REJECTED
          - MNO_PROVISIONED
          - MNO_PROVISIONING_FAILED
          example: TCR_ACCEPTED
          title: campaignStatus
          type: string
        createdAt:
          description: Date and time that the brand was created at.
          example: '2021-03-08T17:57:48.801186'
          type: string
        description:
          description: Summary description of this campaign.
          title: Description
          type: string
        directLending:
          description: Direct lending or loan arrangement.
          title: Directlending
          type: boolean
        embeddedLink:
          description: Does message generated by the campaign include URL link in SMS?
          title: Embeddedlink
          type: boolean
        embeddedLinkSample:
          description: Sample of an embedded link that will be sent to subscribers.
          title: EmbeddedLinkSample
          type: string
        embeddedPhone:
          description: Does message generated by the campaign include phone number in SMS?
          title: Embeddedphone
          type: boolean
        failureReasons:
          description: Failure reasons if campaign submission failed
          title: failureReasons
          type: string
        helpKeywords:
          description: Subscriber help keywords. Multiple keywords are comma separated without space.
          title: Helpkeywords
          type: string
        helpMessage:
          description: Help message of the campaign.
          title: Helpmessage
          type: string
        isNumberPoolingEnabled:
          description: Indicates whether the campaign has a T-Mobile number pool ID associated with it.
          title: isNumberPoolingEnabled
          type: boolean
        messageFlow:
          description: Message flow description.
          title: Messageflow
          type: string
        numberPool:
          description: Does campaign utilize pool of phone numbers?
          title: Numberpool
          type: boolean
        optinKeywords:
          description: Subscriber opt-in keywords. Multiple keywords are comma separated without space.
          title: Optinkeywords
          type: string
        optinMessage:
          description: Subscriber opt-in message.
          title: Optinmessage
          type: string
        optoutKeywords:
          description: Subscriber opt-out keywords. Multiple keywords are comma separated without space.
          title: Optoutkeywords
          type: string
        optoutMessage:
          description: Subscriber opt-out message.
          title: Optoutmessage
          type: string
        privacyPolicyLink:
          description: Link to the campaign's privacy policy.
          title: PrivacyPolicyLink
          type: string
        sample1:
          description: Message sample. Some campaign tiers require 1 or more message samples.
          title: Sample1
          type: string
        sample2:
          description: Message sample. Some campaign tiers require 2 or more message samples.
          title: Sample2
          type: string
        sample3:
          description: Message sample. Some campaign tiers require 3 or more message samples.
          title: Sample3
          type: string
        sample4:
          description: Message sample. Some campaign tiers require 4 or more message samples.
          title: Sample4
          type: string
        sample5:
          description: Message sample. Some campaign tiers require 5 or more message samples.
          title: Sample5
          type: string
        subUsecases:
          description: Campaign sub-usecases. Must be of defined valid sub-usecase types. Use `/10dlc/enum/usecase` operation to retrieve list of valid sub-usecases
          items:
            type: string
          title: Subusecases
          type: array
          uniqueItems: true
        subscriberOptin:
          description: Does campaign require subscriber to opt-in before SMS is sent to subscriber?
          title: Subscriberoptin
          type: boolean
        subscriberOptout:
          description: Does campaign support subscriber opt-out keyword(s)?
          title: Subscriberoptout
          type: boolean
        tcrBrandId:
          description: Unique identifier assigned to the brand by the registry.
          example: BBRAND1
          title: TcrBrandid
          type: string
        tcrCampaignId:
          description: Unique identifier assigned to the campaign by the registry.
          example: CCAMP1
          title: TcrCampaignid
          type: string
        termsAndConditions:
          description: Is terms & conditions accepted?
          title: Termsandconditions
          type: boolean
        termsAndConditionsLink:
          description: Link to the campaign's terms and conditions.
          title: TermsAndConditionsLink
          type: string
        updatedAt:
          description: Date and time that the brand was last updated at.
          example: '2021-03-08T17:57:48.801186'
          type: string
        usecase:
          description: Campaign usecase. Must be of defined valid types. Use `/10dlc/enum/usecase` operation to retrieve usecases available for given brand.
          title: Usecase
          type: string
        webhookFailoverURL:
          description: Failover webhook to which campaign status updates are sent.
          example: https://example.com/failover-webhook
          title: WebhookFailoverURL
          type: string
        webhookURL:
          description: Webhook to which campaign status updates are sent.
          example: https://example.com/webhook
          title: WebhookURL
          type: string
      required:
      - tcrBrandId
      - tcrCampaignId
      title: TelnyxDownstreamCampaign
      type: object
    SharedCampaignRecordSet:
      properties:
        page:
          title: Page
          type: integer
        records:
          items:
            $ref: '#/components/schemas/SharedCampaign'
          title: Records
          type: array
        totalRecords:
          title: Totalrecords
          type: integer
      title: SharedCampaignRecordSet
      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_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/10dlc_Error'
          type: array
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    CampaignSharingStatus:
      properties:
        downstreamCnpId:
          title: Downstreamcnpid
          type: string
        sharedDate:
          title: Shareddate
          type: string
        sharingStatus:
          title: Sharingstatus
          type: string
        statusDate:
          title: Statusdate
          type: string
        upstreamCnpId:
          title: Upstreamcnpid
          type: string
      title: CampaignSharingStatus
      type: object
    TelnyxDownstreamCampaignRecordSet:
      properties:
        page:
          title: Page
          type: integer
        records:
          items:
            $ref: '#/components/schemas/TelnyxDownstreamCampaign'
          title: Records
          type: array
        totalRecords:
          title: Totalrecords
          type: integer
      title: TelnyxDownstreamCampaignRecordSet
      type: object
    SharedCampaign:
      description: Campaign is generated by the 10DLC registry once the corresponding campaign request is approved. Each campaign is assigned a unique identifier - **campaignId**. Once a campaign is activated, limited information is published to the NetNumber OSR service for consumption by members of the ecosystem. When a campaign is suspended(reversible) or expired(non-reversible), campaign data is deleted from the OSR service. Most attributes of campaignare immutable, including **usecase**, **vertical**, **brandId** and **cspId**.
      properties:
        brandId:
          description: Alphanumeric identifier of the brand associated with this campaign.
          title: Brandid
          type: string
        campaignId:
          description: Alphanumeric identifier assigned by the registry for a campaign. This identifier is required by the NetNumber OSR SMS enabling process of 10DLC.
          title: Campaignid
          type: string
        createDate:
          description: Unix timestamp when campaign was created.
          title: Createdate
          type: string
        status:
          description: 'Current campaign status. Possible values: ACTIVE, EXPIRED. A newly created campaign defaults to ACTIVE status. '
          title: Status
          type: string
        usecase:
          description: Campaign usecase. Must be of defined valid types. Use `/10dlc/enum/usecase` operation to retrieve usecases available for given brand.
          title: Usecase
          type: string
      required:
      - brandId
      - campaignId
      - usecase
      title: SharedCampaign
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    UpdatePartnerCampaignRequest:
      properties:
        webhookFailoverURL:
          description: Webhook failover to which campaign status updates are sent.
          example: https://webhook.com/9010a453-4df8-4be6-a551-1070892888d6
          title: WebhookURL
          type: string
        webhookURL:
          description: Webhook to which campaign status updates are sent.
          example: https://webhook.com/67ea78a8-9f32-4d04-b62d-f9502e8e5f93
          title: WebhookURL
          type: string
      title: UpdateCampaignRequest
      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