Test our APIs

For testing purpose only

 Contents
1. Introduction ................................................................................................... 3
1.1 Authorization Token ......................................................................................... 3
1.2 Refresh Token .................................................................................................. 5
2. Header Registration ....................................................................................... 6
2.1 Register a Header ............................................................................................ 6
3. Content Template Registration ........................................................................ 9
3.1 Register a Content Template ............................................................................ 9
4. Consent Template Registration ...................................................................... 12
4.1 Register a Consent Template ......................................................................... 12
5. Annexure ....................................................................................................... 14
5.1 Status Codes .................................................................................................. 14
5.2 Categories ...................................................................................................... 15

2 Powered by
 1. Introduction

This REST API document describes the API details and the fields to be sent on the API to:

• Register a new Header

• Register a new Content Template
• Register a New Consent Template

You must Whitelist the IP addresses from which you will be sending these API requests, before sending any
requests.

Please use this document to test our APIs only, before integrating. Data will be wiped daily.

1.1 Authorization Token

Invoke this API to get the access and refresh tokens. Access token is required to invoke any further API
requests. The request and response will be in JSON format.

Username: Use your DLT ID

Password: Use Generate/Reset password link on the portal (This password will be sent to your registered
email).

The access token is valid for 24 hours from the time it is created. The user must get a new access token
every 24 hours.

The refresh token is valid for 30 days, post which you must invoke the below API again to get e new
refresh token.

URL: https://XX.XX.XX.XXX/api/token/

Method: POST

Parameters:

Parameter Data Type Description

username string (20) DLT Entity ID for the account

password string (20) Password generated on Telco portal for Enterprise API

Note: Access token must be passed in authorization header as the bearer token.

Eg: Authorization: Bearer <access token>

3 Powered by
 Response:

The response will be in JSON format.

Success response:
{
“refresh”:”eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4
cCI6MTU0ODM5MzU5NCwianRpIjoiYjFlZGFjYzE3ZTcxNGIwYmIyMzJkYzRlM2ZmYzFiNjM
iLCJ1aWQiOjk1fQ.GrUjW4shdeQHk4rKhK19kPs5bedX3baaAt1UgeuEtTo”
“access”:”eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXwIjox
NTQ1ODg3OTk0LCJqdGkiOiIwYjVhMmQzMWYyYmM0NmE3YWI2MjZlZDAzMTA4ZDFk
NyIsInVpZCI6OTV9.joB_MjW1tCrFXGOJGROnIUE0-cBaC5U-mYQ0B6qoqp8”
}

Failed response:

If no User is found with the passed credentials:

{
"status": 407,
"message": "Invalid login credentials"
}

If account status is not active:

{
"status": 405,
"message": "PE not active"
}

If API access is not enabled:

{
"status": 424,
"message": "API not enabled for this account"
}

4 Powered by
 1.2 Refresh Token
Invoke this API request to get new access token for authorization. The request and response will be JSON
format.

Refresh token in the response from request (sec 1.1) must be passed as parameter to this API request. The
refresh token is valid for 30 days and need to get new token by using API method in section 1.1

URL: https://XX.XX.XX.XXX/api/token/refresh

Method: POST

Parameters:

Parameter Data Type Description

refresh String Refresh token that was received in 1.1

Response:
The response will be in JSON format.

Success response:
{
“access”:”eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxN
TQ1ODg3OTk0LCJqdGkiOiIwYjVhMmQzMWYyYmM0NmE3YWI2MjZlZD
AzMTA4ZDFkNyIsInVpZCI6OTV9.joB_MjW1tCrFXGOJGROnIUE0-cBaC5U-
mYQ0B6qoqp8”
}

5 Powered by
 2. Header Registration
Header is a unique combination of 3-6 characters representing the Brand Name of the message sender.
As per the TCCCPR regulation the sender ID/source address/A-Party address is termed as ‘Header’. You
can use this API to register a new Header for your Enterprise by using the below API. The Promotional
Headers must be numeric and the headers for all the Other types (Transactional, Service Implicit and
Service Explicit) must be Alphabet or Alphanumeric.

2.1 Register a Header

Use the below API request to register a header for your Enterprise. The request and response will be in
JSON format and method will be ‘POST’.

URL: https://XX.XX.XX.XXX/api/header

Parameters:

Parameter Type Mandatory/ Optional Description

Your Entity ID which is assigned after
Eid String (20) Mandatory
registering on the portal.
Type of Header - P/O
P - Promotional
Htype String (2) Mandatory O – Other
(Transactional/Service Implicit (SI)/Service
Explicit (SE)).
Category ID.
Hctgy Integer Mandatory
Refer Annexure 5.2
Header Name (Numeric for Promotional
Hdr String (6) Mandatory category, Alphabet/Alphanumeric for all
Other Types).
Description of Header, must be
Hdesc String (100) Mandatory alphanumeric special characters allowed
are (),.!@#%*_&-$

Callback URL to be notified about the

cburl String (100) Optional
status changes of the header.

Types of headers based on the SMS category:

1. Promotional: These messages are related to marketing purposes and are intended for promoting a
product or a service. Promotional SMSs are sent to the Non DND numbers.

Headers for sending Promotional SMS must be of 6 numeric and based on the relevant business category.
(Refer Annexure 5.2)

6 Powered by
 Examples: Promotional messages headers: 234567, 345678, 456789, 578901 and in API must use htype
as “P” and hctgy as 2 and header must be “234567”

2. Other: The Other category comprises of Transactional, Service Implicit (SI) and Service Explicit (SE).

2.1 Transactional: As per the latest TRAI Guidelines, only the OTP SMS sent by banks will come under
the category of Transactional SMS. Transactional SMS can be used only by banks for sending One
Time Password (OTP) to its clients. All banks including National / Scheduled / Government / Private
and MNC Banks can send OTP to their clients from the Transactional route.

Note: Banks can use Transactional route for sending OTP only. Headers for Transactional details,
amount debited, credited, account status and all other bank messages must not be registered as
Transactional.

2.2 Service Implicit: Informative messages other than Banks OTP come under this category. Important
notifications such as purchase updates, order alerts, payment status, reminders, booking
confirmations, OTP SMS from other sites and other crucial updates must be registered as Service
Implicit.

2.3 Service Explicit: Sending offer/marketing SMS to your registered users will come under this category.
These SMS can only be sent to the registered customers after receiving their consent.

Headers Registration guidelines for sending Transactional, Service Implicit and Service Explicit messages

For Non-Government Entities: For Alphabetic/Alphanumeric headers, length should always be between
3-6 (Min:3 Max:6).

Examples: HDFCBK, gevtc, gbv5, KAR.

For Government Entities:

i. For numeric header, it should always start with 1 and header length should be in between 3-5 numeric.
Examples: 123, 12321

ii. For Alphabet/Alphanumeric header length should always be in between 3-6 (Min:3 Max:6).

Examples: gotb, govtcd, gov3, 333g.

Sample API request:

Request:
{
"eid": “1123456789012345678”,
"htype": “P”,
"hctgy": 1,
"hdr": “123434”,
"desc": “Sample Creation of header”
}

7 Powered by
 Response:
The response will be in JSON format and it contains status, message and hid (max length 19). The status
200 indicates the header request is accepted by DLT API platform and returns19-digit unique reference
hid (Header ID).

Parameter Type Mandatory/ Optional Description

Refer Annexure 5.1 for list of
status Integer Mandatory
statuses
Header id generated for this
Hid String (20) Mandatory
transaction.
Relevant message to identify
Msg String (200) Mandatory the reason for failure/success.
Refer Annexure 5.1

Success response:
{
"status": 200,
“hid”: "1156789012345678234",
"msg": "Header request submitted successfully”
}
Failure response:
Any status other than 200 indicates a failure response.

Sample1: API Internal error

{
"status": 500,
"msg": "System error"
}

Sample2: If user passes invalid value in header type parameter.

{
"status": 403,
"msg": “Invalid Argument value or type – htype "
}

8 Powered by
 3. Content Template Registration
As per the new TCCCPR 2018 regulation, it is mandatory for an Entity to register their SMS content as a
Content Template on DLT platform. Content templates can be used to send messages to the subscribers
only after approval. You can use variables in the content template for Dynamic data, to use a variable,
use {#var#} in the content template.

3.1 Register a Content Template

The below API request to register a Content Template for an Enterprise. The request and response will
be in JSON format and method will be ‘POST’.

URL: https://XX.XX.XX.XXX/api/content_template
Parameters:
Parameter Type Mandatory/ Optional Description
Your Entity ID which is assigned after
Eid String (20) Mandatory
registering on the portal.
Type of Template - P/T/SI/SE
"P" - Promotional
“T” - Transactional
Ttype String (2) Mandatory
“SI” - Service Implicit
“SE” - Service Explicit
Example: ”P”
Category ID.
Ctgy Integer Mandatory
Refer Annexure 5.2
Headers array (Max 5 are allowed per
request)
Hdrs Array Mandatory Header Names (Numeric for Promotional and
Alphabets/Alphanumerics for all the Other
Types)
Message Type,
Optional values allowed:
msgtype Integer
(Default:1) 1-Text
2-Regional
Active consent Template ID
Cstid String (20) Optional (Must pass only if Template Type is “P” or
“SE”)
Active Brand Name, that has been registered
bname String (50) Optional
on the Platform.
Template Name and Only ascii characters are
tname String (50) Mandatory
allowed.
Template Message
Tmsg String (10000) Mandatory
Refer Rule v

Callback URL which will notify about the

cburl String (100) Optional
status of the Content Template

9 Powered by
 Rules:

i. Category(ctgy) is mandatory for all Templates.

ii. Consent Template ID (cstid) can be passed only for Promotional and Service Explicit Content
Templates and it is an optional parameter.
iii. You can define Variables in below format only.
{#var#}
iv. Multiline templates must be separated with \n in template message.
v. If Message Type is 1 (Text) only ascii characters are allowed in template message If Message Type
is 2 (Regional) must contain at least one non-ascii character in template message.
vi. A maximum of 5 headers are supported per request in “hdrs” array.

The sample API request:

Request:
{
"eid": “1123456789012345678”,
"ttype": “P”,
"ctgy": 1,
"hdrs": [“123434”, “123434”, “122434”],
"msgtype": 1,
"cstid": “1134567890123456782”,
"bname": “TestBrand”,
"tname": “Sample Creation of Template Name”,
"tmsg": “Sample Creation of Template Message”
}

Response:
The response will be in JSON format and it contains status, message and ctid(max length 19). The status
200 indicates the Content Template request is accepted by DLT API platform and returns19-digit unique
reference ctid (Content Template ID).

Parameter Type Mandatory/ Optional Description

Refer Annexure 5.1 for list of
status Integer Mandatory
status
Content Template id for this
ctid String (20) Mandatory
transaction
Relevant message to identify the
msg String (200) Mandatory reason for failure/success.
Refer Annexure 5.1

Success response:
{
"status": 200,
“ctid”: "1145678901234567823",
"msg": "Template request submitted successfully”
}

10 Powered by
 Failure response:
Any status other than 200 indicates a failure response.

Sample1: API Internal error

{
"status": 500,
"msg": "System error"
}

Sample2: If user passes invalid value in template type parameter

{
"status": 403,
"msg": “Invalid Argument value or type – ttype"
}

11 Powered by
 4. Consent Template Registration
A consent template is a Template that will be stored on the DLT post approval. This Consent Template
contains the Name of the Consent Template, Brand name and the Scope of Consent. The Enterprise
name, Brand name and Scope of Consent will be shared with the subscriber as a part of the Consent
Acquisition Message. Based on the Scope of Consent, the subscriber will decide whether to give consent
or not. Principal Entity must register its Consent Templates and get authorization from a subscriber o be
able to send Promotional and Service-Explicit messages.

4.1 Register a Consent Template

Use the below API request to register a Consent Template for a Principal Entity or Enterprise. The request
and response will be in JSON format and method will be ‘POST’.

URL: https://XX.XX.XX.XXX/api/consent_template

Parameters:

Mandatory/
Parameter Type Description
Optional
Your Entity ID which is assigned after
eid String (20) Mandatory
registering on the portal.
Consent Template Name - Only
Mandatory
tname String (50) alphanumeric and these (.#,-_) special
Min: 2 Max: 50
characters.
Brand Name and
Mandatory
bname String (50) Only alphanumeric and these (.#,-_) special
Min: 2 Max: 50
characters.
Scope of Consent Template
Mandatory
scope String (200) Only alphanumeric and these characters
Min: 2 Max: 50
()/:.;!,&#$%^*\[]{}-@_are allowed
Callback URL on which you will notified
cburl String (100) Optional
about the status of the Consent Template.

The sample API request is given below

Request:
{
"eid ": “1123456789012345678”,
"tname ": “test”,
"bname": “testbrand”,
"scope ": “test scope of consent”
}

12 Powered by
 Response:
The response will be in JSON format and it contains status, message and cstid (max length 19). The status
200 indicates the Consent Template request is accepted by DLT API platform and returns19-digit unique
reference cstid (Consent Template ID).

Parameter Type Mandatory/ Optional Description

Refer Annexure 5.1 for list of
status Integer Mandatory
status
Consent Template Id for this
cstid String (20) Mandatory
transaction
Relevant message to identify the
msg String( 200) Mandatory reason for failure/success.
Refer Annexure 5.1

Success response:
{
"status": 200,
“ctid”: "1145678901234567823",
"msg": "Consent Template request submitted successfully”
}

Failure response:
Any status other than 200 indicates a failure response.

Sample1: API Internal error

{
"status": 500,
"msg": "System error"
}

Sample2: If user passes invalid value in scope parameter

{
"status": 403,
"msg": “Invalid Argument value or type – scope"
}

13 Powered by
 5. Annexure
5.1 Status Codes
Code Description
200 Success

401 Invalid token or Token expired

402 Invalid method

403 Invalid Argument value or type - <parameter name>

404 Parameter is missing

405 PE not active

406 PE validity expired

407 Invalid login credentials

408 <parameter info> not active

409 <parameter info> not found

410 IP not whitelisted

411 PE ID mismatch

412 <parameter info> already registered

413 Invalid <parameter info>

414 Category is allowed only for promotional template messages

415 Maximum 5 headers are allowed

416 Duplicate headers in hdrs

417 Invalid template variable in tmsg

419 Template cannot be linked to Blacklisted <parameter info>

420 <parameter info> already linked to Content Template

421 <parameter info> not linked to Content Template

422 At least one header must be linked to Content Template

423 <parameter info> approval pending

424 API not enabled for this account

500 System error

14 Powered by
 5.2 Categories

ID Description

0 Other

1 Banking/Insurance/Financial products/credit cards

2 Real Estate

3 Education

4 Health

5 Consumer goods and automobiles

6 Communication/Broadcasting/Entertainment/IT

7 Tourism and Leisure

8 Food and Beverages

15 Powered by