---
schema_version: "1"
id: 41ad64d6e12b37ebf06d1c67d49f440d26ae6facfe6bc8c59873777585458b8d
title: POST /messaging/v1/sms/definitions
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/guides/mc-apis/createSMSSendDefinition.md
canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_transactional_messaging_sms/createSMSSendDefinition.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 7417207555eb31eb3edc6da3f37dfc9309590c35ea840ae6359b077f2d5a0872
products:
- Marketing Cloud Engagement APIs and Programmatic Languages
- Marketing Cloud
---
# POST /messaging/v1/sms/definitions
Creates an SMS send definition.
## JSON Parameters
| Name | Type | Description |
| --------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `definitionKey` | String | Required. A unique key for the SMS send definition object. |
| `name` | String | Required. A unique name for the send definition. |
| `content.message` | String | Required. The message content for the send definition. You can personalize the message by including AMPscript in the message body. |
| `status` | String | The state of the send definition. Possible values are `active` or `inactive`. A message sent to an active definition is processed and delivered. A message sent to an inactive definition isn’t processed or delivered. Instead, the message is queued for later processing for up to three days. |
| `description` | String | A description of the send definition. |
| `subscriptions.shortCode` | String | Required. The short or long code to send messages from. |
| `subscriptions.countryCode` | String | The country code associated with the short code. Don’t specify this value for long codes unless your account configuration requires it. |
| `subscriptions.keyword` | String | Required. The keyword used to track messages. |
| `subscriptions.autoAddSubscriber` | Boolean | Indicates whether to add a recipient as a short code subscriber by contact key. If this value is `false`, the message is rejected if the subscriber’s contact key doesn’t exist. The default value is `true`. |
| `subscriptions.updateSubscriber` | Boolean | Indicates whether to update the subscriber data for the recipient, including their mobile number. The default value is `true`. |
| `options.urlShortenerOptions.IsLinkShorteningEnabled` | Boolean | Indicates whether to enable URL shortening for URLs in the message body. |
| `options.urlShortenerOptions.isSubscriberTrackingEnabled` | Boolean | Indicates whether to enable subscriber-level tracking for URLs in the message body. The value is `true` if the value of `shortenerType` is `SFMC`. |
| `options.urlShortenerOptions.shortenerType` | String | The type of URL shortener to use in the send definition. The only accepted value is `SFMC`. |
| `options.SmsMessageRegulatoryAuthorityTemplateId` | String | The ID of the DLT template used in the SMS. This attribute applies only to senders based in India.
**Important:** If you use link shortening, set this field. Otherwise, the shortened URL won't include the required regulatory header, and the SMS won't deliver. Ensure that SMS_DLT_TEMPLATES business rule is enabled. |
**note:** If the value of `updateSubscriber` is `true`, then `autoAddSubscriber` must also be `true`. The API returns an error if `updateSubscriber` is `true` but `autoAddSubscriber` is `false`.
## Response Parameters
| Name | Type | Description |
| --------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `requestId` | String | A unique identifier for the request. |
| `name` | String | The name of the SMS send definition. |
| `definitionKey` | String | The unique key of the SMS send definition. |
| `definitionId` | String | A unique identifier for the send definition. |
| `description` | String | A description of the send definition. |
| `status` | String | The state of the send definition. Possible values are `Active`, `Inactive`, or `Deleted`. |
| `createdDate` | String | The date and time when the definition was created. |
| `modifiedDate` | String | The date and time when the definition was last modified. |
| `content.message` | String | The message content for the send definition. |
| `subscriptions.shortCode` | String | The short or long code associated with the send definition. |
| `subscriptions.countryCode` | String | The country code associated with the short code for the send definition. |
| `subscriptions.keyword` | String | The keyword used to track messages. |
| `subscriptions.autoAddSubscriber` | Boolean | Indicates whether to add a recipient as a short code subscriber by contact key. |
| `subscriptions.updateSubscriber` | Boolean | Indicates whether the subscriber data for the recipient is updated. |
| `options.urlShortenerOptions.IsLinkShorteningEnabled` | Boolean | Indicates whether URL shortening is enabled for URLs in the message body. |
| `options.urlShortenerOptions.isSubscriberTrackingEnabled` | Boolean | Indicates whether subscriber-level tracking is enabled for URLs in the message body. |
| `options.urlShortenerOptions.shortenerType` | String | The type of URL shortener used in the send definition. |
| `options.SmsMessageRegulatoryAuthorityTemplateId` | String | The ID of the DLT template used in the SMS. |
## Usage
To associate a short code to a send definition, use the alphabetic `countryCode` and numeric `shortCode` attributes.
```
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /messaging/v1/sms/definitions/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"definitionKey": "account-reset",
"name": "account-reset",
"description": "Using SMS Transactional API",
"content": {
"message": "%%FirstName%%, your 2FA token is %%password%%"
},
"subscriptions": {
"shortCode": "8201221",
"countryCode": "US",
"keyword": "PASSWORD"
},
"options": {
"urlShortenerOptions" : {
"isLinkShorteningEnabled": true,
"isSubscriberTrackingEnabled":true,
"shortenerType":"SFMC"
},
"smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
}
}
```
A successful request produces a `201 Created` response that includes information about the send definition, as shown in this example.
```json
{
"requestId": "582bec09-6d04-4222-bbba-cea616495596",
"name": "account-reset",
"definitionKey": "account-reset",
"description": "Using new SMS Transactional API",
"status": "Active",
"createdDate": "2019-05-14T21:05:00",
"modifiedDate": "2019-05-14T21:05:00",
"content": {
"message": "%%FirstName%%, your 2FA token is %%password%%"
},
"subscriptions": {
"shortCode": "8201221",
"countryCode": "US",
"autoAddSubscriber": true,
"updateSubscriber": true,
"keyword": "PASSWORD"
},
"options": {
"urlShortenerOptions": {
"isLinkShorteningEnabled": true,
"isSubscriberTrackingEnabled": true,
"shortenerType": "SFMC"
},
"smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
}
}
```
### SMS Send Definition with a Long Code
To associate a long code or international phone number to a send definition, add the numeric country code at the beginning of the phone number. Then, use this number as the `shortCode` attribute. Don't use the alphabetic `countryCode` attribute unless your account configuration requires it.
```
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /messaging/v1/sms/definitions/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"definitionKey": "account-reset",
"name": "account-reset",
"description": "Using new SMS Transactional API",
"content": {
"message": "%%FirstName%%, your 2FA token is %%password%%"
},
"subscriptions": {
"shortCode": "971234567890",
"keyword": "PASSWORD"
},
"options": {
"urlShortenerOptions" : {
"isLinkShorteningEnabled": true,
"isSubscriberTrackingEnabled":true,
"shortenerType":"SFMC"
},
"smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
}
}
```
A successful request produces a `201 Created` response that includes information about the send definition, as shown in this example.
```json
{
"requestId": "582bec09-6d04-4222-bbba-cea616495596",
"name": "account-reset",
"definitionKey": "account-reset",
"description": "Using new SMS Transactional API",
"status": "Active",
"createdDate": "2019-05-14T21:05:00",
"modifiedDate": "2019-05-14T21:05:00",
"content": {
"message": "%%FirstName%%, your 2FA token is %%password%%"
},
"subscriptions": {
"shortCode": "971234567890",
"autoAddSubscriber": true,
"updateSubscriber": true,
"keyword": "PASSWORD"
},
"options": {
"urlShortenerOptions": {
"isLinkShorteningEnabled": true,
"isSubscriberTrackingEnabled": true,
"shortenerType": "SFMC"
},
"smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
}
}
```
## HTTP Responses
| Response | Reason |
| ------------------ | ------------------------------------- |
| `201 Created` | Send definition created. |
| `409 Conflict` | Send definition exists on the server. |
| `400 Bad Request` | Invalid request. |
| `403 Forbidden` | Failed to pass authorization. |
| `500 Server Error` | Internal error. |