US 10DLC API Installation
A quick start to install a US 10 DLC number
Last updated
Was this helpful?
A quick start to install a US 10 DLC number
Last updated
Was this helpful?
10DLC is a local 10-digit phone number that requires Brand & Use Case registration and supports throughput levels suitable for A2P SMS campaigns. 10DLC is sanctioned by mobile carriers for A2P messaging and is intended to provide a reliable user experience, better deliverability, and higher messaging speed. To find out more about 10DLC see the following
To setup a new channel to send SMS messages using a United states 10 digit long code number the following steps are required
Some of the following requests will lead to additional workspace charges. Ensure you before proceeding
The following API requests can only be made using a valid access key and attached to an access role with the an access policy that at least specifies the permissions to the resources outlined in each section below.
If you do not already have a US 10DLC number available in your workspace you can find one to purchase .You can filter by country, prefix, number type and number capabilities.
The ID for the organization.
d0b85ccc-b63a-4e81-b698-c359d77d250eLimits the number of results to return per page. The default value is 10 and maximum is 99. If the nextPageToken is defined on response, you can use it to get remaining numbers. To know more, refer to the pagination section.
10Pagination token that keeps of track of the current position in the list. Use it to query remaining results. If not provided, the first page is returned. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.
A 2-digit ISO 3166-1 country code array.
["US","NL"]Used to filter numbers belonging to a specific local area-code. It MUST be used in conjunction with the countryCodes filter. Always provide prefixes in full international format.
+1212The following example will return the first available US local number required for use with 10DLC registration.
Once you have found an available number you can purchase this by providing the number (in E.1624 format) and the country (using a two digit ISO code).
A successful request to this endpoint will start a recurring monthly subscription based on the monthly cost of the number
The following example will purchase the number if it still available and you have sufficient balance in your workspace wallet. Provide number in E.1624 format and country in 2 digit ISO code (e.g. US)
You can set up a Web Hook subscription to be notified of any brand or campaign event. Brand and camping creation work in sync, and subscribing to all related events will automate the 10DLC registration process.
The Following example will Create a subscrscrition listing to all Brand Related events
The Following example will Create a subscription listing to all Brand Related events
After creating a brand, this will be submitted for approval by the campaign registry. The brand must be approved before you can register a campaign with the campaign registry. Brand registration may take some time.
You can find the full list of brand management endpoints here
The following example will create a new brand that will be submitted for registration with the campaign registry.
The final result of If your brand is not being accepted or your company is not part of the Russell 3000 stock index you can also request additional vetting. For brands that are not part of the Russell 3000 stock index this can provide access to higher messaging throughputs (depending on your vetting score)
The following example will create a new brand vetting request that will be submitted for registration with the campaign registry. You must have previously created a brand
To reduce the likelihood of rejection, ensure you are familiar with 10dlc registration examples and best practices. Specifically
Check this article for tips on how to write an effective Campaign description
Check this article on how to write an effective messageFlow
Most 10DLC rejections are caused by unclear or incomplete description and/or messageFlow
Handling Attachments
You will need to attach proof of opt-in and/or consent collection. To facilitate troubleshooting by both your team and the Bird team, we strongly recommend including a URL (e.g., to a third-party hosting service like Google Drive) directly in the messageFlow JSON field.
Note: The attachment vector is only supported via the UI and is not currently supported via API POST requests.
If you are registering a 10DLC campaign on behalf of third parties (e.g., your clients), you are required to also include your own contact information as part of the registration process. You can do so by including a resellerId in your POST campaign calls
You can create a Reseller via UI
you can retrieve information via the following method
Ensure your reseller status is active before creating a campaign with it
After creating a campaign, this will be submitted for approval by the campaign registry. The campaign must be approved before you can associate this with an SMS channel. Campaign registration can take 1-2 weeks to be approved.
You can find the full list of campaign management endpoints here
The following example will create a new campaign that will be submitted for registration with the campaign registry. Your associated brand must be approved
Same as done before, you can create a workspace subscription to listen to Channel Status changes
The example below will create a workspace-wide subscription tracking all updates regarding your channels you can use to track channels' status changes
The following example will create a new SMS connector with an approved 10DLC campaign and US local number:
Once you have created your SMS connector, this will create an SMS channel. You can then get your channel ID to before setting up channel webhooks
The following example will get the connector you have created in the previous step. Parse the channel.channelId to get the id of your new SMS channel
Once your channel has been installed you will then need to setup a webhook subscription to receive status updates and inbound messages
The following request example will create a new SMS subscription for inbound and outbound messages
Inbound messages
Outbound messages
10DLC numbers can only send traffic to the USA when linked to a campaign. Number Campaign link is an A-sync process requiring confirmations from multiple carriers.
The bird will only consider a number linked if all major USA carriers acknowledge the links. Delays in carrier acknowledgment can vary between 15 minutes to several hours and are usually longer around peak linking hours (afternoon/evening USA Pacific time)
Based on whether you have subscribed or not to channel events, you can determine the readiness of a given channel in 2 ways
if you have a "channel.updated" event subscription, each change in a channel status will trigger an event. You can associate those events to the number you have used to install the channel by referring to "identifier" field. A channel ready to send SMS will have "status": "active".
This could happen if the number linked to its campaigns is not acknowledged or the 10DLC registration experiences issues. In this case, the "useCaseStatus" 's value will not be "ok"
In this case "useCaseStatus" will be "ok"
Before you can use a US 10DLC number to send SMS messages, you must be and campaign with an external registry called the campaign registry.
A successful request to this endpoint will mean you are charged a fee. If you later need to update or resubmit your brand there may be additional fees.
A successful request to this endpoint will mean you are charged a fee.
Once your brand status is approved you can then create your first . Brands can have multiple campaigns. A campaign describes what types of messages you will send from your SMS channel.
The ID for the workspace.
d386a801-ee8d-4aba-a7e4-78671bd3b11eLimits the number of results to return per page. The default value is 10 and maximum is 99. If the nextPageToken is defined on response, you can use it to get remaining numbers. To know more, refer to the pagination section.
10Pagination token that keeps of track of the current position in the list. Use it to query remaining results. If not provided, the first page is returned. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.
Order in which to retrieve the results. By default, the orders are in ascending order date. To get the results in descending order, set this parameter to true.
falseOK
A successful request to this endpoint will mean you are charged a and a three month minimum commitment fee. If you later need to update or resubmit your brand there may be additional fees.
if so you can query the and wait for the "useCaseStatus" to turn to "ok"
Assigns Long Code Numbers to the current workspace, charging the wallet for their subscription price. When creating LCNs as a User, all specified Number Stock Items should be reserved.
The ID for the workspace.
d386a801-ee8d-4aba-a7e4-78671bd3b11eThe unique identifiers of the numbers you want to buy. You can buy up to 25 numbers at a time. This operation will incur wallet charges for the numbers. Before buying the number, you must reserve it.
Create a brand at workspace level. This means it will be available only for this workspace. A brand registration is mandatory due to compliance requirements.
The ID for the workspace.
d386a801-ee8d-4aba-a7e4-78671bd3b11eLegal entity type. It can't be updated when the brand is approved.
PRIVATE_PROFITPossible values: First or given name. Applicable to entity type.
JohnLast or Surname. Applicable to entity type.
DoeDisplay or marketing name your brand.
ABC MobileLegal company name. This should match the legal company name used to register your EIN/Tax ID.
ABC Inc.Government assigned corporate tax ID. EIN is 9-digits in the U.S.
111111111The 2 letter ISO country of registration submitted with your EIN / Tax ID registration.
USValid phone number in e.164 international format.
+12024567890Street number and name.
123 6th AveCity name
New YorkState. Must be a 2 letter state code for US states.
NYPostal code. Must be a 5 digit zip code for the United States.
10001ISO 2 character country code.
USValid email address of brand support contact.
johndoe@abc.comStock symbol. Required for entityType PUBLIC.
ABCStock exchange. Required for entityType PUBLIC.
NASDAQPossible values: Brand website URL.
https://example.comVertical or industry segment of the brand.
RETAILAlternate business identifier.
Alternate business identifier type. Required if altBusinessId is provided.
Business contact email.
Create a brand vetting in a workspace. Brand vetting should be requested when the brand is not getting approved, or if the customer needs a higher throughput.
The ID for the workspace.
d386a801-ee8d-4aba-a7e4-78671bd3b11eA unique identifier for the brand.
Identifies the vetting classification.
STANDARDPossible values: External vetting provider ID for the brand.
To create a campaign, it is essential to ensure that the brand has already been approved. Campaigns can only be initiated under the umbrella of brands that meet this prerequisite. Once a campaign is created, it cannot begin directing traffic immediately. Instead, it must go through a formal approval process. Only after the campaign has been reviewed and approved it will be authorized to send traffic.
The ID for the workspace.
d386a801-ee8d-4aba-a7e4-78671bd3b11eA unique identifier for the brand.
Campaign name
A use case that best matches the purpose of the campaign.
If use case is MIXED or LOW_VOLUME mixed an array of 2-5 use cases.
A detailed description of what the campaign is for.
Whether messages will contain links. Provide at least one sample containing a link.
Whether messages will contain phone number. Provide at least one sample containing a phone number.
Whether a campaign will be associated with more than 50 numbers e.g. customer service use case.
Whether a campaign contains age-gated content based on carrier/ctia guidelines.
Whether a campaign includes content related to direct lending or loan arrangements.
Confirm customer opt in is collected and processed.
Confirm customer opt out is collected and processed.
Confirm an info message is returned if a customer sends "HELP".
Between 1-5 sample messages. If directLending, embeddedPhone, embeddedLink is true provide relevant examples.
Up to 5 attachments.
Provide details of how the customer will opt into this campaign. If you have a live web opt-in provide the URL and ensure the page has details on the T&Cs/data collection for opting in, and how to opt out.
Help message of the campaign. A help message shall state the name of the service, contact (email or call centre), OPT IN and OPT OUT keywords.
A comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info.
A comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT.
A comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT.
Provide an example of the message that will be sent after a customer has opted in.
Provide an example of the message that will be sent after a customer has opted out.
Indicates the campaign follows CTIA messaging principles and best practices.
UUID of the reseller associated with this campaign. The specified reseller MUST be ACTIVE.
To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL. You can create multiple webhook subscriptions to route different types of events to various URLs as needed. Event filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent. If you want to handle multiple interactionTypes, you’ll need to create separate webhook subscriptions for each.
The ID for the workspace.
b4e02c85-c6d2-4b15-8885-e09671799c61The ID for the organization.
cb28a94e-8557-4394-80ea-5bbd2170d434To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL. You can create multiple webhook subscriptions to route different types of events to various URLs as needed. Event filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent. If you want to handle multiple interactionTypes, you’ll need to create separate webhook subscriptions for each.
The ID for the workspace.
b4e02c85-c6d2-4b15-8885-e09671799c61The ID for the organization.
cb28a94e-8557-4394-80ea-5bbd2170d434