You are here:
Get Token API Specification
Use this information to provide token representation of plain text values. Marketing Cloud Engagement uses this API method to retrieve the token representation of a plain text value.
Engagement sends an HTTP POST request to the URI for the token server you provide as part of a tokenized sending process. This request contains a list of token values, and your token server responds with the list of token values and associated tokens.
If the request is sent without a token, the response JSON in the tokens array does not contain any data. If there is only a single tokenValue in the request and your token server does not provide a token for it, the response includes an empty array for the tokens property in the JSON response.
The API gets the token representation of phone number data. The token is stored in the database instead of the source phone number from an inbound SMS message.
Prerequisites
Enable SSL at the endpoint. Use basic or OAuth client credentials authentication with server-side IP allowlisting to authenticate client calls.
JSON Request Body Format
Marketing Cloud Engagement sends a request using the application/json content type with the body containing a mandatory array of token values called tokenValues. Each tokenValue object in the array contains these properties.
| Parameter Name (key) | Type | Required | Description | |
|---|---|---|---|---|
| tokenValues | None | array (required) | Yes | Array of tokenValue objects for which the server returns tokens. |
| Each tokenValue object includes these properties: | ||||
| tokenRequestId | string (required) | Yes | The UUID (generated per token). | |
| tokenValue | string (required) | Yes | The clear normalized mobile number or email address. | |
| tokenType | string (required) | Yes | Identifies the token as a MobileNumber or Email. | |
| privateCode | string | No | The private short or long code for mobile phone sends. | |
JSON tokenValues Sample Request
{
"tokenValues": [
{
"tokenRequestId": "abc123thn567",
"tokenValue": "13172237777",
"tokenType": "MobileNumber",
"privateCode": "46356",
},
{
"tokenRequestId": "abc098thn654",
"tokenValue": "13175559911",
"tokenType": "MobileNumber",
"privateCode": "45356",
}
]
}JSON Response Body Format
The response returned in an application/json content type block includes an HTTP status code.
| Code | Message | Notes |
|---|---|---|
| 200 | OK | Request successfully processed |
| 400 | Bad Request | Improperly formatted request |
| 500 | Internal Server Error | Unexpected error while processing request |
| 503 | Service Unavailable | Service currently unavailable |
Body and Token Object
| Parameter Name (key) | Type | Required | Description |
|---|---|---|---|
| token | array (required) | Yes | Array of returned tokens |
| Property | Type | Required | Description |
|---|---|---|---|
| tokenRequestId | string (required) | Yes | The UUID provided as part of the request - this value must match one of the values from the request. |
| token | string (required) | Yes | The token used to represent a marketing contact. |
| subscriberKey | string | No | This value includes the subscriber key for the contact. Provide a value or a random key will be provided. |
MobileConnect Considerations
Tokens maintain a one-to-one relationship with phone numbers. Phone number tokens use the same token value even if that mobile number appears for multiple contacts. If you plan on using Triggered Sends (messageContact API), provide the real country in front of the mobile token. The entire value must not exceed 15 characters.
Sample Response
{
"tokens": [
{
"tokenRequestId": "abc123thn567",
"token": "999911112222",
"subscriberKey": "abc123456xyz”
},
{
"tokenRequestId": "abc098thn654",
"token": "999911112233",
"subscriberKey": "123abcxyz456”
}
]
}