# DLT Parameters in an SMS API: Entity ID, Header, Template ID and Telemarketer ID Explained

If you have ever integrated an SMS API for the Indian market, you have probably hit this moment: the API returns a success response, your dashboard shows the message as "submitted", and the phone never buzzes.

Nine times out of ten, the cause is a **DLT parameter** problem. A wrong Template ID, a header that was never mapped, or a message body that drifts one word from the registered template is enough for the operator to reject the message.

This guide explains what DLT parameters are, how they fit into an SMS API request, and how to debug them. For the full reference of every parameter, see the main guide on [DLT parameters for Bulk SMS](https://www.techtonetworks.com/bulk-sms/dlt-parameters).

## What is DLT, and why does an API care?

DLT stands for Distributed Ledger Technology. In India, the Telecom Regulatory Authority of India (TRAI) uses a DLT platform, run separately by each major operator, as the registry of who is allowed to send commercial SMS, from which sender name, and with what content.

Under the TRAI Telecom Commercial Communications Customer Preference Regulations (TCCCPR), every commercial SMS must be traceable to registered records. The operator checks your message against those records in real time. Your SMS API is simply the pipe that carries the identifiers the operator needs to run that check.

That is why a DLT-compliant SMS API asks for more than a phone number and a message body. It needs the **DLT parameters**.

## The core DLT parameters

| Parameter | What it identifies | Where it comes from |
| --- | --- | --- |
| **Principal Entity ID (PE ID)** | Your business as a registered sender | Issued when you register as a Principal Entity on an operator's DLT portal |
| **Header (Sender ID)** | The name or code shown as the sender, such as a six-character alphabetic header | Registered by you on the DLT portal, then approved |
| **Content Template ID** | The exact approved message format | Generated when a template is approved on the DLT portal |
| **Telemarketer ID (TM ID)** | The messaging provider that delivers on your behalf | Assigned to the telemarketer (your SMS provider) and bound to your account |

Providers name these fields differently. One API may call them `entity_id`, `template_id` and `sender`; another may use `peid`, `tid` and `header`. The meaning is the same, so always check your provider's documentation for the exact field names. The [DLT parameters page](https://www.techtonetworks.com/bulk-sms/dlt-parameters) lists each field in plain terms so you can map them to whatever naming your integration uses.

## How an operator validates one message

Think of a single SMS passing through four checks:

1. **Is the sender registered?** The Entity ID must exist and be active.
2. **Is the header allowed?** The header must be registered under that entity and approved.
3. **Does the content match?** The message body must fit an approved template, and the Template ID you sent must be the one for that template.
4. **Is the delivery chain valid?** The provider carrying the message must be bound to your entity as an authorised telemarketer.

If any check fails, the message is blocked. Importantly, the rejection often happens **after** your API call has already succeeded, which is why DLT errors look like "silent failures" from the developer side.

## What a DLT-aware API request looks like

Here is a generic example. The field names are illustrative only, so substitute the ones from your provider's documentation.

```json
{
  "to": "9198XXXXXXXX",
  "header": "ABCDEF",
  "entity_id": "<your-principal-entity-id>",
  "template_id": "<approved-template-id>",
  "message": "Your OTP is 482913. Valid for 5 minutes. Do not share it with anyone."
}
```

Three things matter here:

- **The message must match the template.** The fixed text must be identical, character for character. Only the variable portions may change.
- **The Template ID must belong to that exact message.** Sending a valid Template ID with a different body is a common cause of rejection.
- **The header must be linked to the template.** On most DLT portals a template is approved against specific headers, so a header that exists but is not mapped to that template can still fail.

A full breakdown of each field, with examples, is in the [DLT parameters guide](https://www.techtonetworks.com/bulk-sms/dlt-parameters).

## Template variables: where most mismatches happen

DLT templates use placeholders, written as `{#var#}`, for the parts of a message that change per recipient: names, OTP codes, order numbers, amounts and links.

Example approved template:

```plaintext
Dear {#var#}, your OTP for login is {#var#}. It is valid for {#var#} minutes. Do not share it with anyone.
```

Example sent message:

```plaintext
Dear Anita, your OTP for login is 482913. It is valid for 5 minutes. Do not share it with anyone.
```

Common mistakes:

- Extra spaces, changed punctuation or different capitalisation in the fixed text.
- A variable value that is too long for what the template allows. Operators may apply length limits to variable content.
- Putting a URL in a variable when the template was not approved for links. Links generally need to be whitelisted or registered, so check the current rules on your DLT portal.
- Using a transactional template to send content that is actually promotional.

## Template categories change what you can send

Every template is registered under a content category, and the category affects both how the message is treated and when it can be delivered:

- **Transactional**: OTPs and alerts triggered by a customer's own action, such as bank transaction alerts.
- **Service (implicit or explicit)**: information related to an existing relationship. Explicit service messages depend on recorded consent.
- **Promotional**: marketing and offers, which are subject to the recipient's DND preferences and delivery-hour restrictions.
- **Government**: messages from government bodies.

Picking the wrong category is not just a delivery risk. Misclassified traffic can lead to template or header action by operators. Your API request should use the category that matches the template as registered. Where your provider exposes a template-type field, set it to match the registration.

## Header suffixes

TRAI has moved headers towards a suffix that shows the message category, so the recipient and the network can see whether a message is promotional, service, transactional or governmental at a glance. If you registered headers a long time ago, confirm on your DLT portal and with your provider how they appear today, and update your integration if your provider has changed the format it expects.

## PE-TM chain binding

This is the parameter area that catches teams out most often now. TRAI requires the delivery chain between the Principal Entity (you) and each Telemarketer in that chain to be declared on the DLT platform. In practice, it means you must approve your SMS provider as your telemarketer on the DLT portal. If that binding is missing or incomplete, messages can fail even when your Entity ID, header and template are all correct.

If your provider, or any intermediary above them, changes, the binding needs to be redone. Check this early when you migrate from one SMS provider to another.

## A practical debugging checklist

When a message does not arrive, work through this in order:

1. Confirm the **Entity ID** is the one registered on the DLT portal, with no typos or stray spaces.
2. Confirm the **header** is approved, active and mapped to the template you are using.
3. Confirm the **Template ID** matches the message you actually sent.
4. Compare the fixed text of your message against the template, one character at a time.
5. Check the **template category** against the nature of the message.
6. Confirm the **PE-TM chain** binding is approved for your provider.
7. Check the delivery report for the failure reason code, and ask your provider to map it to a DLT cause.

For reference descriptions of each parameter, and how they fit together in one place, keep the [DLT parameters guide](https://www.techtonetworks.com/bulk-sms/dlt-parameters) open next to your integration.

## Quick reference

| Symptom | Likely DLT cause |
| --- | --- |
| API accepts the request but no SMS arrives | Template mismatch, unmapped header or missing PE-TM binding |
| Only some messages fail | Variable content breaking the template, or a long variable value |
| OTPs delayed or blocked while others deliver | Wrong category or template configuration |
| Everything fails after switching provider | PE-TM chain not rebound to the new telemarketer |

## Wrapping up

DLT parameters are not paperwork that sits outside your code. They are part of the message itself, and each one answers a specific question the operator asks before it lets an SMS through: who you are, what name you are using, what you are saying and who is carrying it.

Get those four right, keep your message bodies faithful to the registered templates, and most "mystery" delivery failures disappear. For the complete parameter-by-parameter reference, read the [DLT parameters guide for Bulk SMS](https://www.techtonetworks.com/bulk-sms/dlt-parameters).

*DLT rules and portal workflows are updated by TRAI and the operators from time to time. Always confirm current requirements on your DLT portal or with your SMS provider before going live.*