Get Started with 10DLC API

Overview

10-digit long code (10DLC) is a service offered by US mobile network operators (MNO) to explicitly allow A2P messaging over long code phone numbers. 10DLC numbers provide benefits over regular long codes, such as lower surcharges, higher throughput, and less content filtering.

To register for 10DLC service, businesses must

• Provide brand information about the business
• Provide campaign information about messaging use cases
• Specify the numbers to use for 10DLC

Plivo lets businesses perform these tasks on the console.

Some of our customers — namely, businesses that resell messaging services — need to perform 10DLC registration tasks repeatedly, and therefore need a programmatic solution. To aid these customers, Plivo offers a set of APIs for completing 10DLC-related operations.

How does it work?

Consider a hypothetical messaging provider, Ovilp Corp., that provides a messaging platform for organizations that send messages in the US. Its customers are hospitals and medical practitioners that might send messages such as

• Appointment alerts for patients
• Marketing announcements to opted-in customers
• Two-factor authentication (2FA) codes for individuals to use to log in to patient portals

Ovilp also has a console for their customers’ tech teams that requires 2FA to log in.

Per 10DLC guidelines, Ovilp must register its business and each of its clients’ businesses as separate brands and specify their respective use cases (campaigns). That means Ovilp must

• Register itself as a brand to send 2FA codes, and register brands for each of its clients.
• Create unique campaigns for its own and each of its brands’ use cases.
• Link Plivo long codes to campaigns.

A document in our support portal provides details about brand and campaign registration.

Walkthrough

To complete all of those tasks, Ovilp can use Plivo’s 10DLC APIs. The first steps involve Ovilp’s own use of 10DLC.

• Since Ovilp sends out its own messages, it needs to register its main business on the Plivo console.
• Once its brand is successfully registered, Ovilp must create campaigns that detail its intended use cases.
• After successfully registering campaigns, Ovilp can use the number linking API to register numbers that will be used to send messages to their customers, or do it from the console.

These steps ensure that Ovilp’s own messages are registered for 10DLC service.

Next, Ovilp must register each of its clients for 10DLC.

Creating a profile

Before registering a brand or campaigns, Ovilp should identify each of its clients’ types of business — private, public, nonprofit, government, or individual. Plivo uses that information and the Profile API to create a profile for each client, providing the correct business information.

A profile contains information about Plivo customers’ (and their clients’) businesses, such as legal name, authorized contact, and business registration details. Profiles help Plivo understand its customers and help us unlock multiple communication services like 10DLC and STIR/SHAKEN (coming soon).

Code

curl -i --user auth_id:auth_token \
    -H 'Content-Type: application/json' \
    -d '{
        "profile_alias": "john_new",
        "customer_type": "reseller",
        "entity_type": "public",
        "company_name": "ABC Inc.",
        "vertical": "Entertainment",
        "plivo_subaccount" :"SAXXXXXXXXXXXXXXXXMM",
        "ein": "122321231",
        "ein_issuing_country":"US", 
        "address": {
            "street": "123 West St",
            "city": "New York",
            "state": "NY",
            "postal_code": "10001",
            "country": "US"
        },
        "stock_symbol": "HIBYE",
        "stock_exchange": "NYSE",
        "alt_business_id_type": "DUNS",
        "alt_business_id": "ABC",
        "website": "hibye.com",
        "authorized_contact": {
            "first_name": "john",
            "last_name": "doe",
            "email": "johndoe@example.com",
            "title": "Doe",
            "seniority": "admin",
            "phone": "12125557777"
        }
    
    }'\
    https://api.plivo.com/v1/Account/{auth_id}/Profile/

Registering a brand

Once each client has a profile, Ovilp can register a brand for each client using the Brand API. Each profile can create only one brand. For optimal throughput for Standard brands, opt in to vetting.

Code — Standard

curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
            "brand_alias": "gov234t",
            "profile_uuid": "d61eaaaa-18b1-4473-8810-0b9d80573aa9",
            "brand_type":"STANDARD",
            "secondary_vetting":true
        }' \
        https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/

Check the registration_status field in the Brand API response to check the status of brand registration. It will show up as “COMPLETED” when the brand has been successfully registered with The Campaign Registry (TCR), the company that handles 10DLC registrations on behalf of US carriers.

Code

curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/{brand_id}/   

Registering a campaign

Once the brand is registered, Ovilp can create campaigns to meet the messaging needs of each client either using the console or programmatically using Plivo’s Create Campaign API.

Code

curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
            "brand_id": "{brand_id}",
            "vertical": "INSURANCE",
            "usecase": "MIXED",
            "sub_usecases":["2FA","ACCOUNT_NOTIFICATION", "CUSTOMER_CARE", "DELIVERY_NOTIFICATION", "FRAUD_ALERT"],
            "description": "OTP registration",
            "direct_lending": true,
            "affiliate_marketing": false,
            "embedded_link": false,
            "embedded_phone": false,
            "age_gated": false,
            "subscriber_optin": true,
            "subscriber_optout": true,
            "subscriber_help": true,
            "sample1": "Hi, your OTP to log in is 1234",
            "sample2": "Your order {ID} is out for delivery"
        }' \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/

After you create a campaign you can check its status using the Campaign API. Check the registration_status field in the Campaign API response to check the status of campaign registration. It will show up as “ACTIVE” when the campaign has been successfully registered.

Code

curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/

Linking numbers to a campaign

Once the campaigns have been registered, Ovilp can link its clients’ existing Plivo long code phone numbers with a campaign using the Number API. Keep in mind that you can link no more than 49 numbers to a Standard campaign.

Also be aware that sending the same content across multiple source numbers specifically to evade content filters is called snowshoeing and violates all carriers’ acceptable use policies. A snowshoeing violation may result in suspension of the campaign.

Code

curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
        "numbers": ["12125557778"]
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/

You can track the status of your number registration using Number API. Check the status field in the Number response. A value of COMPLETED indicates the number has been successfully linked to the campaign. To link more numbers, you can make more calls to the API.

Code

curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/12125557778/

Unlinking numbers to a campaign

If you no longer need a source number to be linked with a campaign, you can unlink it using the Number API. Unlinking a number is irreversible; if you do it mistakenly, you must link the number to the campaign again to use it for 10DLC.

If you unrent a number, Plivo automatically unlinks it from 10DLC campaigns.

Code

curl -X DELETE -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/12125557778/

Start messaging

Once all the brands and campaigns are registered and the numbers are linked, Ovilp and its clients can start using them to send messages to US customers on 10DLC registered routes.

Things to keep in mind before using 10DLC APIs

You must have a standard Plivo account with sufficient credits to cover the costs associated with 10DLC registration.

10DLC processes depend on integration with some third-party providers. Requests remain in the “processing” stage until all of the processes are complete. You can get the latest status using Plivo’s GET APIs for Brand, Campaign, and Number endpoints.