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.

Note Provide a token for every tokenRequestId included in the request. Tokens cannot include an empty string.

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.

Example An oil change facility uses the same single mobile phone number for several vehicles belonging to the same family. These subscribers aren't differentiated.

Sample Response

{
  "tokens": [
    {
      "tokenRequestId": "abc123thn567",
      "token": "999911112222",
	"subscriberKey": "abc123456xyz”
    },
    {
      "tokenRequestId": "abc098thn654",
      "token": "999911112233",
	"subscriberKey": "123abcxyz456”
    }
  ]
}