Leveraging Public APIs with 10 DLC
Objective
Leveraging Vonage public APIs with 10 DLC.
Applies To
- 10 DLC
- Public APIs
Procedure
For a description of the available APIs, see our developer documentation.
1. Calls to Perform to Create a Brand
All brands created will be verified by the TCR (The Campaign Registry). This verification only allows to create campaigns, but will limit the brand to the lowest throughput possible. In order to ensure the best throughput is assigned to your campaigns, you will need to vet the brand.
Note that any brand failing the verification will also need to go through vetting.
- Create a brand
- Apply for vetting
The vetting can take a few days, depending on the home country of the entity to vet or the need to manually verify some details. To ensure the best outcomes, please make sure to provide the information as they appear on the official records for your home country.
If the vetting fails, you can appeal. Please reach out to our support teams.
- Alternative: Import existing vetting
Leveraging the endpoint: PUT
https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/vetting/requests/
In order to import an existing vetting, you will need to know the following details:
evp_id (vetting agency), vetting_id, vetting_token
Campaign Verify (CV) political vets can only be imported via this endpoint into Vonage currently.
For more information on how to obtain a CV political vet, please check their website.
Important information: Vets are not transferrable between service providers due to regulatory limitations. We will let you know if this changes in the future.
Customers may be able to import such vet via the vetting import endpoint if they can obtain the required information.
Wait until the vetting steps are completed before moving to the next part and creating campaigns.
1. a. Sole Proprietor brands process
If you are creating a Sole Proprietor brand, there are some specifics to consider.
- Sole Proprietor brands are not able to request external vets
- Sole Proprietor brands require different information than typical brands
- Sole Proprietor brands do not have an EIN number or Tax ID
- Sole Proprietor brands must be located in the USA or Canda
- Sole Proprietor brands must go through a different data validation process
- Sole Proprietor brands must provide a valid "mobile_phone" number and trigger an OTP verification to complete the brand verification
Please check this article for more details on the specifics of Sole Proprietor brands.
2. Calls to Perform to Create a Campaign
Before you can create a campaign, you need to make sure that your brand is qualified to create campaigns for this use-case. This is a required step for all new use-case. Please also follow this guide for more details on the requirements to provide when creating a campaign.
- Verify the brand is qualified (required for each new campaign use case)
GET 'https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/usecase/:usecase'
- Create a campaign
POST 'https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns'
{
... *
}
* Please check API description for the detail of the attributes to provide
Once the campaign has been created, a request is sent for approval to all the US carriers. Please note that you cannot link numbers to your campaign until all carriers have approved the campaign. It can take up to 7 days for all carriers to approve the campaign.
3. Importing partner campaigns (created on the TCR platform - resellers)
Requirements:
- Have signed a contract with TCR and create brands and campaigns directly from TCR's platform
- Reach out to your Vonage Account Manager to get the feature enabled for your account
- Be registered as a reseller (have a reseller ID - check this article for more)
Once the feature is enabled, you can leverage our public API endpoint to make calls from your parent account (main api_key):
POST 'https://api-eu.vonage.com/v1/10dlc/partnercampaigns/import'
{
"account_id": "abcdef01",
"campaign_id": "string",
"label": "string"
}
"account_id": api_key of the account where the campaign will be imported. Note that only this api_key will be able to link numbers to that campaign
"label": optional attribute to allow customers to setup a "friendly" name for their campaign
The call must be authenticated using the main api_key account to succeed.
4. Link Number(s) to Your Campaign
Once all carriers have approved the campaign, you can link numbers to it. Please note that all campaigns (except special use cases) have their throughput limit set at the campaign level, so having more than 1 number linked to the campaign will not increase the amount of messages that can be sent.
5. Process to follow when updating a brand
When updating a brand, the information may need to be reverified by the vetting providers (Aegis, WMC, CV) to confirm that the new information is still verifiable and genuine.
At Vonage, we keep the two steps separated to ensure clarity on the customer's side.
1. Update the 10DLC Brand information in Vonage's and TCR's databases
PATCH 'https://api-eu.vonage.com/v1/10dlc/brands/:brand_id'
{
...
}
2. If applicable, proceed to re-verify the new brand information
POST 'https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/revet'
This endpoint applies for re-verification of the brand information to Aegis (vetting agency)
This endpoint is charged $4 to the customer
This table is provided to us by TCR, to define what brand changes require our customer to apply for a re-verification of the brand information:
Property Name | Re-Scoring Required | Note |
ein, ein_issuing_country, entity_type | Yes | Update allowed if brand has not been successfully vetted |
All other attributes | Optional |
6. Process to follow when updating a campaign
Some attributes can only be setup at the campaign creation, if you need to update one of those protected attributes, please cancel the campaign and create a brand new campaign.
Example: If you need to enable the number pooling feature on a campaign, the "number_pool" attribute must be set to True. This can only be configured at the campaign creation.
1. Update the 10DLC Campaign information in Vonage's and TCR's databases
PATCH 'https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id
{
... // see table below
}
The attributes that can be set when updating a campaign are:
Attribute | Type | Notes |
label | string | |
description | string | min 40 characters |
reseller_id | string |
Required if campaign belong to a brand representing a different entity |
sample_one -> sample_five | string | min 20 characters |
message_flow | string | min 40 characters |
opt_in_keywords opt_out_keywords help_keywords |
string |
default "STOP" & "HELP" separate keywords by ',' |
opt_in_message opt_out_message help_message |
string | min 20 characters |
auto_renewal | boolean |
set to false to cancel campaign action cannot be reverted |
Important Consideration
If you have a need for more than 49 numbers to be linked to a single campaign, you need to set number_pool to true when declaring the campaign. In addition to that, you will need to open a support ticket or reach out to your account manager providing additional information. More on this here.
Comments
0 comments
Please sign in to leave a comment.