OpenAPI Specification
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 Campaign 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: Campaign operations
name: Campaign
paths:
/10dlc/campaign:
get:
description: Retrieve a list of campaigns associated with a supplied `brandId`.
operationId: GetCampaigns
parameters:
- in: query
name: brandId
required: true
schema:
title: Brandid
type: string
- 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
- campaignId
- -campaignId
- createdAt
- -createdAt
- status
- -status
- tcrCampaignId
- -tcrCampaignId
title: Sort
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignRecordSet_CSP'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: List Campaigns
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaign/acceptSharing/{campaignId}:
post:
description: Manually accept a campaign shared with Telnyx
operationId: AcceptCampaign
parameters:
- description: TCR's ID for the campaign to import
in: path
name: campaignId
required: true
schema:
description: TCR's ID for the campaign to import
pattern: ^C[A-Z0-9]{5,8}$
title: Campaignid
type: string
responses:
'202':
content:
application/json:
schema:
additionalProperties: true
example: {}
type: object
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: Accept Shared Campaign
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaign/usecase/cost:
get:
operationId: GetCampaignCost
parameters:
- in: query
name: usecase
required: true
schema:
title: Usecase
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignCost'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: Get Campaign Cost
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaign/{campaignId}:
delete:
description: Terminate a campaign. Note that once deactivated, a campaign cannot be restored.
operationId: DeactivateCampaign
parameters:
- in: path
name: campaignId
required: true
schema:
title: Campaignid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignDeletionResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: Deactivate campaign
tags:
- Campaign
x-latency-category: responsive
get:
description: Retrieve campaign details by `campaignId`.
operationId: GetCampaign
parameters:
- in: path
name: campaignId
required: true
schema:
title: Campaignid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TelnyxCampaign_CSP'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: Get campaign
tags:
- Campaign
x-latency-category: responsive
put:
description: Update a campaign's properties by `campaignId`. **Please note:** only sample messages are editable.
operationId: UpdateCampaign
parameters:
- in: path
name: campaignId
required: true
schema:
title: Campaignid
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCampaignRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TelnyxCampaign_CSP'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: Update campaign
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaign/{campaignId}/appeal:
post:
description: 'Submits an appeal for rejected native campaigns in TELNYX_FAILED or MNO_REJECTED status. The appeal is recorded for manual compliance team review and the campaign status is reset to TCR_ACCEPTED. Note: Appeal forwarding is handled manually to allow proper review before incurring upstream charges.'
operationId: AppealCampaign
parameters:
- description: The Telnyx campaign identifier
in: path
name: campaignId
required: true
schema:
example: 5eb13888-32b7-4cab-95e6-d834dde21d64
format: uuid
type: string
requestBody:
content:
application/json:
schema:
properties:
appeal_reason:
description: Detailed explanation of why the campaign should be reconsidered and what changes have been made to address the rejection reason.
example: The website has been updated to include the required privacy policy and terms of service.
type: string
required:
- appeal_reason
type: object
description: Appeal request payload
required: true
responses:
'200':
content:
application/json:
example:
appealed_at: '2025-08-06T15:30:45.123456+00:00'
schema:
properties:
appealed_at:
description: Timestamp when the appeal was submitted
format: date-time
type: string
type: object
description: Appeal recorded successfully. Campaign status updated to TCR_ACCEPTED for manual compliance review.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/10dlc_Error'
description: Campaign not in appealable status or invalid request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/10dlc_Error'
description: Campaign not found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: Submit campaign appeal for manual review
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaign/{campaignId}/mnoMetadata:
get:
description: Get the campaign metadata for each MNO it was submitted to.
operationId: GetCampaignMnoMetadata
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:
$ref: '#/components/schemas/MnoMetadata'
description: Successful Response. It constains a map of usecase metadata for each MNO. The key is the network ID of the MNO (e.g. 10017), the value is the mno metadata for the usecase. The metadata may also include some MNO specific fields.
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
5XX:
content:
application/json:
schema:
$ref: '#/components/schemas/10dlc_Errors'
description: Unexpected Error
summary: Get Campaign Mno Metadata
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaign/{campaignId}/operationStatus:
get:
description: Retrieve campaign's operation status at MNO level.
operationId: GetCampaignOperationStatus
parameters:
- in: path
name: campaignId
required: true
schema:
title: Campaignid
type: string
responses:
'200':
content:
application/json:
schema:
additionalProperties: true
example:
'10017': APPROVED
'10035': REVIEW
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 campaign operation status
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaign/{campaignId}/osr/attributes:
get:
operationId: GetCampaignOsrAttributes
parameters:
- in: path
name: campaignId
required: true
schema:
title: Campaignid
type: string
responses:
'200':
content:
application/json:
schema:
additionalProperties: true
example:
brandId: 00000000-0000-0000-0000-000000000000
msg_class: E
status: '7'
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 OSR campaign attributes
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaign/{campaignId}/sharing:
get:
operationId: GetCampaignSharingStatus
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:
$ref: '#/components/schemas/CampaignSharingChain'
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:
- Campaign
x-latency-category: responsive
/10dlc/campaignBuilder:
post:
description: Before creating a campaign, use the [Qualify By Usecase endpoint](https://developers.telnyx.com/api-reference/campaign/qualify-by-usecase) to ensure that the brand you want to assign a new campaign to is qualified for the desired use case of that campaign. **Please note:** After campaign creation, you'll only be able to edit the campaign's sample messages. Creating a campaign will entail an upfront, non-refundable three month's cost that will depend on the campaign's use case ([see 10DLC Costs section for details](https://developers.telnyx.com/api-reference/campaign/get-campaign-cost)).
operationId: PostCampaign
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TelnyxCampaign_CSP'
description: Successful Response
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/10dlc_Error'
description: Bad Request
'402':
content:
application/json:
schema:
$ref: '#/components/schemas/10dlc_Error'
description: Insufficient Funds
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: Submit Campaign
tags:
- Campaign
x-latency-category: responsive
/10dlc/campaignBuilder/brand/{brandId}/usecase/{usecase}:
get:
description: This endpoint allows you to see whether or not the supplied brand is suitable for your desired campaign use case.
operationId: GetUsecaseQualification
parameters:
- in: path
name: usecase
required: true
schema:
title: Usecase
type: string
- in: path
name: brandId
required: true
schema:
title: Brandid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UsecaseMetadata'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
4XX:
$ref: '#/components/responses/10dlc_GenericErrorResponse'
summary: Qualify By Usecase
tags:
- Campaign
x-latency-category: responsive
components:
schemas:
UsecaseMetadata:
properties:
annualFee:
description: Campaign annual subscription fee
title: Annualfee
type: number
maxSubUsecases:
description: Maximum number of sub-usecases declaration required.
title: Maxsubusecases
type: integer
minSubUsecases:
description: Minimum number of sub-usecases declaration required.
title: Minsubusecases
type: integer
mnoMetadata:
additionalProperties: true
description: Map of usecase metadata for each MNO. Key is the network ID of the MNO (e.g. 10017), Value is the mno metadata for the usecase.
title: Mnometadata
type: object
monthlyFee:
description: Campaign monthly subscription fee
title: Monthlyfee
type: number
quarterlyFee:
description: Campaign quarterly subscription fee
title: Quarterlyfee
type: number
usecase:
description: Campaign usecase
title: Usecase
type: string
title: UsecaseMetadata
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
MnoMetadata:
additionalProperties: true
properties:
'10999':
$ref: '#/components/schemas/MnoMetadataItem'
title: MnoMetadata
type: object
CampaignDeletionResponse:
properties:
message:
title: Message
type: string
record_type:
title: Record Type
type: string
time:
title: Time
type: number
required:
- time
title: CampaignDeletionResponse
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
CampaignRecordSet_CSP:
properties:
page:
title: Page
type: integer
records:
items:
$ref: '#/components/schemas/TelnyxCampaignWithAssignedCount_CSP'
title: Records
type: array
totalRecords:
title: Totalrecords
type: integer
title: CampaignRecordSet_CSP
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
TelnyxCampaign_CSP:
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:
ageGated:
description: Age gated content in campaign.
title: Agegated
type: boolean
autoRenewal:
description: Campaign subscription auto-renewal status.
title: Autorenewal
type: boolean
billedDate:
description: Campaign recent billed date.
title: Billeddate
type: string
brandDisplayName:
description: Display or marketing name of the brand.
example: ABC Mobile
title: Branddisplayname
type: string
brandId:
description: Unique identifier assigned to the brand.
example: d2ca9d69-641b-4131-83fa-5d0744f4c8a9
title: Brandid
type: string
campaignId:
description: Unique identifier for a campaign.
example: 823d6b1a-6ed6-41a3-9c50-c8ff41b682ba
title: Campaignid
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
createDate:
description: Unix timestamp when campaign was created.
title: Createdate
type: string
cspId:
description: Alphanumeric identifier of the CSP associated with this campaign.
title: Cspid
type: string
description:
description: Summary description of this campaign.
title: Description
type: string
directLending:
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
isTMobileNumberPoolingEnabled:
description: Indicates whether the campaign has a T-Mobile number pool ID associated with it.
title: isTMobileNumberPoolingEnabled
type: boolean
isTMobileRegistered:
description: Indicates whether the campaign is registered with T-Mobile.
title: IsTMobileRegistered
type: boolean
isTMobileSuspended:
description: Indicates whether the campaign is suspended with T-Mobile.
title: isTMobileSuspended
type: boolean
messageFlow:
description: Message flow description.
title: Messageflow
type: string
mock:
description: Campaign created from mock brand. Mocked campaign cannot be shared with an upstream CNP.
title: Mock
type: boolean
nextRenewalOrExpirationDate:
description: When the campaign would be due for its next renew/bill date.
title: Nextrenewalorexpirationdate
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
referenceId:
description: Caller supplied campaign reference ID. If supplied, the value must be unique across all submitted campaigns. Can be used to prevent duplicate campaign registrations.
title: Referenceid
type: string
resellerId:
description: Alphanumeric identifier of the reseller that you want to associate with this campaign.
title: Resellerid
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
status:
description: 'Current campaign status. Possible values: ACTIVE, EXPIRED. A newly created campaign defaults to ACTIVE status. '
title: Status
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
submissionStatus:
description: Campaign submission status
enum:
- CREATED
- FAILED
- PENDING
title: submissionStatus
type: string
subscriberHelp:
description: Does campaign responds to help keyword(s)?
title: Subscriberhelp
type: boolean
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
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
vertical:
deprecated: true
description: 'Business/industry segment of this campaign (Deprecated). Must be of defined valid types. Use `/registry/enum/vertical` operation to retrieve verticals available for given brand, vertical combination.
This field is deprecated.'
title: Vertical
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:
- brandId
- campaignId
- cspId
- description
- mock
- subUsecases
- termsAndConditions
- usecase
title: TelnyxCampaign_CSP
type: object
UpdateCampaignRequest:
properties:
autoRenewal:
default: true
description: Help message of the campaign.
title: Autorenewal
type: boolean
helpMessage:
description: Help message of the campaign.
maxLength: 255
title: Helpmessage
type: string
messageFlow:
description: Message flow description.
maxLength: 2048
title: Messageflow
type: string
resellerId:
description: Alphanumeric identifier of the reseller that you want to associate with this campaign.
maxLength: 8
title: Resellerid
type: string
sample1:
description: Message sample. Some campaign tiers require 1 or more message samples.
maxLength: 255
title: Sample1
type: string
sample2:
description: Message sample. Some campaign tiers require 2 or more message samples.
maxLength: 255
title: Sample2
type: string
sample3:
description: Message sample. Some campaign tiers require 3 or more message samples.
maxLength: 255
title: Sample3
type: string
sample4:
description: Message sample. Some campaign tiers require 4 or more message samples.
maxLength: 255
title: Sample4
type: string
sample5:
description: Message sample. Some campaign tiers require 5 or more message samples.
maxLength: 255
title: Sample5
type: string
webhookFailoverURL:
description: Webhook failover to which campaign status updates are sent.
title: WebhookURL
type: string
webhookURL:
description: Webhook to which campaign status updates are sent.
title: WebhookURL
type: st
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-campaign-api-openapi.yml