Skip to content
10DLC Brand Registration/API reference/
/
List TFN Verifications

Registration (1.0)

Service for creating and listing US 10DLC brand and campaign registrations and TFN Verifications.

The US brand and campaign registration API is an asynchronous process. Most brands and campaign registrations will be completed in a few minutes, but in some scenarios, the process can take several days. The initial release will not include a webhook service, therefore you will need to poll the result of the brand and campaign registrations. We suggest doing this every hour until the registration status is "Approved" or "Rejected".

10DLC Registration steps
Client submits brand registration→brandRegistrations→Sinch
Client gets back brandRegistrationId←{brandRegistrationId}←Sinch
Client polls using brandRegistrationId→brandRegistrations/{brandRegistrationId}→Sinch
Client gets back TCR Brand ID←{brandId}←Sinch
Client checks use-case→campaignRegistration:qualify→Sinch
Client submits campaign registration→campaignRegistration:submit→Sinch
Client gets back campaignRegistrationId←{campaignRegistrationId}←Sinch
Client polls using campaignRegistrationId→campaignRegistrations/{campaignRegistrationId}→Sinch
Client gets back TCR campaign ID←campaignId←Sinch

Download OpenAPI description
10dlc-registration.json
10dlc-registration.yaml
Overview
URL
https://www.sinch.com
Support
Support@sinch.com
License
MIT
Languages
Servers
HTTP 10DLC API Server (Default(US))
https://us10dlc.numbers.api.sinch.com

10DLC Brand Registration

Create or look up brand registration for 10DLC virtual numbers

Operations

10DLC Campaign Registration

10DLC is a system in the United States that allows businesses to send Application-to-Person (A2P) messaging via 10-digit-long-codes (10DLC). It uses a dedicated 10-digit telephone number allocated within the North American Numbering Plan (NANP).

In order to register for a 10DLC campaign, you need to have a 10DLC enabled brand. Create a 10DLC enabled brand before you start, see Brand Registrations for more info.

Before you launch your 10DLC message program, Sinch must review your campaign. We make sure your message program aligns with carrier and industry requirements. Principally we look for alignment with the CTIA 2023 Messaging Principals & Best Practices. If your campaign does not meet these requirements, we will reject it. If we do reject it, you will need to make changes to the campaign and resubmit it for Sinch to review again.

It's important to understand 10DLC compliance requirements as well as other best practices. You should also know the most common reasons why Sinch may reject your campaign . We want to help you get your campaigns approved the first time. Then you can get your message program up and running right away!

Operations

TFN Verification

Create or look up Verifications for Toll-Free Numbers

Operations

Create TFN Verifications

Request

Create a TFN verification.

Security
BasicAuth or OAuth2
Path
projectIdstringrequired

Sinch uses projects to group resources such as contacts and apps together to manage and connect a unique set of keys and secret IDs for all your Sinch API products. To identify a project, it is given a unique alphanumeric identifier that ties it to your account. Your project ID can be found in the Customer Dashboard.

Bodyapplication/jsonrequired

The request body of the TFN Verification to be created

projectIdstringrequired

Your project ID can be found in the Customer Dashboard.

phoneNumberstring^\+[1-9]\d{1,14}$required

Toll-Free Number that is procured, hosted or in the process of hosting with Sinch. Must be in E.164 format.

businessNamestring<= 500 charactersrequired
businessAddress1string<= 500 charactersrequired
businessCitystring<= 500 charactersrequired
businessStatestring<= 500 charactersrequired
businessZipCodestring<= 500 charactersrequired
businessContactFirstNamestring<= 500 charactersrequired
businessContactLastNamestring<= 500 charactersrequired
businessContactEmailstring(email)<= 500 charactersrequired
businessContactPhonestring^\+[1-9]\d{1,14}$required
corporateWebsitestring<= 500 charactersrequired
messageVolumestring<= 500 charactersrequired

Estimate monthly volume of messages from the TFN (accepted values: 10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000, 10000000+)

useCasestring<= 500 charactersrequired

Category of the use case, fetched from the dedicated API.

useCaseSummarystring<= 500 charactersrequired

General idea of the use case and customer.

productionMessageContentstring<= 1000 charactersrequired

Example of message content.

optInWorkflowDescriptionstring<= 500 charactersrequired

Description of the opt-in workflow.

optInWorkflowImageUrlsArray of stringsrequired

Images showing the opt-in workflow.

businessRegistrationNumberstring<= 50 charactersrequired

A legally recognized business registration number.

businessTypestring<= 50 charactersrequired

The type of business, selected from a list of predefined categories.

Enum ValueDescription
SOLE_PROPRIETOR

A business owned and run by one individual.

PRIVATE_PROFIT

A privately-owned company that operates for profit.

PUBLIC_PROFIT

A publicly-traded company that operates for profit.

NON_PROFIT

An organization that uses its surplus revenues to further achieve its purpose or mission.

GOVERNMENT

A government entity or agency.

businessRegistrationCountrystring<= 500 charactersrequired

Country business is registered in.

businessRegistrationTypestring<= 50 charactersrequired

The type of business registration (e.g. EIN, CBN, CRN, NEQ, Provincial Number, VAT, ACN, ABN, BRN)

createdBystring(email)<= 50 characters

The email of the user who initiated the request.

businessAddress2string<= 500 characters
businessCountrystring<= 500 characters
additionalInformationstring<= 500 characters

Any additional information.

campaignVerifyAuthorizationTokenstring(password)<= 500 characterswrite-only

Campaign tokens for customers. This is a sensitive, write-only field.

curl -i -X POST \
  -u <username>:<password> \
  'https://us10dlc.numbers.api.sinch.com/v1/projects/{projectId}/tfnVerification' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "string",
    "createdBy": "user@example.com",
    "phoneNumber": "string",
    "businessName": "string",
    "businessAddress1": "string",
    "businessAddress2": "string",
    "businessCity": "string",
    "businessState": "string",
    "businessZipCode": "string",
    "businessCountry": "string",
    "businessContactFirstName": "string",
    "businessContactLastName": "string",
    "businessContactEmail": "user@example.com",
    "businessContactPhone": "string",
    "corporateWebsite": "string",
    "messageVolume": "string",
    "useCase": "string",
    "useCaseSummary": "string",
    "productionMessageContent": "string",
    "optInWorkflowDescription": "string",
    "optInWorkflowImageUrls": [
      "string"
    ],
    "additionalInformation": "string",
    "businessRegistrationNumber": "string",
    "businessType": "SOLE_PROPRIETOR",
    "businessRegistrationCountry": "string",
    "campaignVerifyAuthorizationToken": "pa$$word",
    "businessRegistrationType": "string"
  }'

Responses

A successful response.

Bodyapplication/json
tfnVerificationIdstring
Response
application/json
{
  "tfnVerificationId": "string"
}

List TFN Verifications

Request

Lists all TFN verifications per project.

Security
BasicAuth or OAuth2
Path
projectIdstringrequired

Sinch uses projects to group resources such as contacts and apps together to manage and connect a unique set of keys and secret IDs for all your Sinch API products. To identify a project, it is given a unique alphanumeric identifier that ties it to your account. Your project ID can be found in the Customer Dashboard.

Query
useCasestring

A use case associated to a verification to be searched

statusesArray of strings(TfnVerificationStatus)
Items Enum ValueDescription
STATUS_UNSPECIFIED

Status not specified.

WAITING

Verification is waiting.

IN_PROGRESS

Verification is in progress.

VERIFIED

TFN has been verified.

REJECTED

TFN has been rejected.

pageSizeinteger(int32)
pageTokenstring
orderBystring
curl -i -X GET \
  -u <username>:<password> \
  'https://us10dlc.numbers.api.sinch.com/v1/projects/{projectId}/tfnVerification?useCase=string&statuses=STATUS_UNSPECIFIED&pageSize=0&pageToken=string&orderBy=string'

Responses

A successful response.

Bodyapplication/json
tfnVerificationsArray of objects(Tfn Verification Base)
totalSizeinteger
nextPageTokenstring
Response
application/json
{
  "tfnVerifications": [
    { … }
  ],
  "totalSize": 0,
  "nextPageToken": "string"
}

Get TFN Verifications

Request

Get information about an existing TFN Verification.

Security
BasicAuth or OAuth2
Path
projectIdstringrequired

Sinch uses projects to group resources such as contacts and apps together to manage and connect a unique set of keys and secret IDs for all your Sinch API products. To identify a project, it is given a unique alphanumeric identifier that ties it to your account. Your project ID can be found in the Customer Dashboard.

tfnVerificationIdstringrequired

The ID of an existing TFN verification

curl -i -X GET \
  -u <username>:<password> \
  'https://us10dlc.numbers.api.sinch.com/v1/projects/{projectId}/tfnVerification/{tfnVerificationId}'

Responses

A successful response.

Bodyapplication/json
projectIdstringrequired

Your project ID can be found in the Customer Dashboard.

phoneNumberstring^\+[1-9]\d{1,14}$required

Toll-Free Number that is procured, hosted or in the process of hosting with Sinch. Must be in E.164 format.

businessNamestring<= 500 charactersrequired
businessAddress1string<= 500 charactersrequired
businessCitystring<= 500 charactersrequired
businessStatestring<= 500 charactersrequired
businessZipCodestring<= 500 charactersrequired
businessContactFirstNamestring<= 500 charactersrequired
businessContactLastNamestring<= 500 charactersrequired
businessContactEmailstring(email)<= 500 charactersrequired
businessContactPhonestring^\+[1-9]\d{1,14}$required
corporateWebsitestring<= 500 charactersrequired
messageVolumestring<= 500 charactersrequired

Estimate monthly volume of messages from the TFN (accepted values: 10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000, 10000000+)

useCasestring<= 500 charactersrequired

Category of the use case, fetched from the dedicated API.

useCaseSummarystring<= 500 charactersrequired

General idea of the use case and customer.

productionMessageContentstring<= 1000 charactersrequired

Example of message content.

optInWorkflowDescriptionstring<= 500 charactersrequired

Description of the opt-in workflow.

optInWorkflowImageUrlsArray of stringsrequired

Images showing the opt-in workflow.

businessRegistrationNumberstring<= 50 charactersrequired

A legally recognized business registration number.

businessTypestring<= 50 charactersrequired

The type of business, selected from a list of predefined categories.

Enum ValueDescription
SOLE_PROPRIETOR

A business owned and run by one individual.

PRIVATE_PROFIT

A privately-owned company that operates for profit.

PUBLIC_PROFIT

A publicly-traded company that operates for profit.

NON_PROFIT

An organization that uses its surplus revenues to further achieve its purpose or mission.

GOVERNMENT

A government entity or agency.

businessRegistrationCountrystring<= 500 charactersrequired

Country business is registered in.

tfnVerificationIdstringread-onlyrequired

The unique identifier for the TFN verification request, generated by the server.

statusstringread-onlyrequired

The current status of the verification request.

Enum ValueDescription
STATUS_UNSPECIFIED

Status not specified.

WAITING

Verification is waiting.

IN_PROGRESS

Verification is in progress.

VERIFIED

TFN has been verified.

REJECTED

TFN has been rejected.

createTimestring(date-time)read-onlyrequired

The timestamp when the verification was created, in UTC (RFC3339 format).

businessRegistrationTypestring<= 50 charactersrequired

The type of business registration (e.g. EIN, CBN, CRN, NEQ, Provincial Number, VAT, ACN, ABN, BRN)

createdBystring(email)<= 50 characters

The email of the user who initiated the request.

businessAddress2string<= 500 characters
businessCountrystring<= 500 characters
additionalInformationstring<= 500 characters

Any additional information.

notesArray of objects(TFN Verification Note Object)read-only

Feedback notes added during the review process.

Response
application/json
{
  "tfnVerificationId": "string",
  "status": "STATUS_UNSPECIFIED",
  "createTime": "2019-08-24T14:15:22Z",
  "projectId": "string",
  "createdBy": "user@example.com",
  "phoneNumber": "string",
  "businessName": "string",
  "businessAddress1": "string",
  "businessAddress2": "string",
  "businessCity": "string",
  "businessState": "string",
  "businessZipCode": "string",
  "businessCountry": "string",
  "businessContactFirstName": "string",
  "businessContactLastName": "string",
  "businessContactEmail": "user@example.com",
  "businessContactPhone": "string",
  "corporateWebsite": "string",
  "messageVolume": "string",
  "useCase": "string",
  "useCaseSummary": "string",
  "productionMessageContent": "string",
  "optInWorkflowDescription": "string",
  "optInWorkflowImageUrls": [
    "string"
  ],
  "additionalInformation": "string",
  "businessRegistrationNumber": "string",
  "businessType": "SOLE_PROPRIETOR",
  "businessRegistrationCountry": "string",
  "businessRegistrationType": "string",
  "notes": [
    { … }
  ]
}

Get TFN Verification use cases

Request

Get a list of valid use cases for creating TFN Verifications

Security
BasicAuth or OAuth2
Path
projectIdstringrequired

Sinch uses projects to group resources such as contacts and apps together to manage and connect a unique set of keys and secret IDs for all your Sinch API products. To identify a project, it is given a unique alphanumeric identifier that ties it to your account. Your project ID can be found in the Customer Dashboard.

curl -i -X GET \
  -u <username>:<password> \
  'https://us10dlc.numbers.api.sinch.com/v1/projects/{projectId}/tfnVerification/useCases'

Responses

A successful response.

Bodyapplication/json
useCasesArray of strings
Response
application/json
{
  "useCases": [
    "string"
  ]
}