---
schema_version: "1"
id: c38ef6de9870cb895561b6b39d5f0aedb0aeba8464b9f44eba97e3e24c4722b5
title: Get Token API Specification
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/mktg/264-0-0/mc_overview_get_token_api_specification.md
canonical_url: https://help.salesforce.com/s/articleView?id=mktg.mc_overview_get_token_api_specification.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: 0d2438563d4649277bdba9bb4ac56f45035e72d3657c641ae95dd8ded69f6b5b
description: 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.
products:
  - Marketing
  - Marketing Cloud Engagement
release: "264"
---
# 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.

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small ">
        <colgroup>
          <col style="width:20%">
          <col style="width:20%">
          <col style="width:20%">
          <col style="width:20%">
          <col style="width:20%">
        </colgroup>
        <thead class="slds-text-title_caps ">
          <tr class="">
            <th scope="colgroup" class="slds-cell-wrap" colspan="2" style="vertical-align:top;" id="d56228e72">Parameter Name (key)</th>
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d56228e75">Type</th>
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d56228e78">Required</th>
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d56228e81">Description</th>
          </tr>
        </thead>
        <tbody>
          <tr class="">
            <td data-label="Parameter Name (key)" class="slds-cell-wrap" rowspan="6" style="vertical-align:top;" headers="d56228e72 ">tokenValues</td>

            <td data-label="Type" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e72 ">None</td>

            <td data-label="Required" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e75 ">array (required)</td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e78 ">Yes</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e81 ">Array of tokenValue objects for which the server returns tokens.</td>

          </tr>
          <tr class="">
            <td class="slds-cell-wrap" colspan="4" style="vertical-align:top;" headers="d56228e72 d56228e75 d56228e78 d56228e81 ">Each tokenValue object includes these
              properties:</td>

          </tr>
          <tr class="">
            <td data-label="Type" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e72 ">tokenRequestId</td>

            <td data-label="Required" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e75 ">string (required)</td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e78 ">Yes</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e81 ">The UUID (generated per token).</td>

          </tr>
          <tr class="">
            <td data-label="Type" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e72 ">tokenValue</td>

            <td data-label="Required" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e75 ">string (required)</td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e78 ">Yes</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e81 ">The clear normalized mobile number or email address.</td>

          </tr>
          <tr class="">
            <td data-label="Type" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e72 ">tokenType</td>

            <td data-label="Required" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e75 ">string (required)</td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e78 ">Yes</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e81 ">Identifies the token as a MobileNumber or Email.</td>

          </tr>
          <tr class="">
            <td data-label="Type" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e72 ">privateCode</td>

            <td data-label="Required" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e75 ">string</td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e78 ">No</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d56228e81 ">The private short or long code for mobile phone sends.</td>

          </tr>
        </tbody>
      </table>

## 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](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-mktg-mc_marketing_cloud_overview-264-0-0-production-enus/2555afdb-8049-4e3c-8043-0e04803e5f16/images/icon_note.png)

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](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-mktg-mc_marketing_cloud_overview-264-0-0-production-enus/2555afdb-8049-4e3c-8043-0e04803e5f16/images/icon_example.png)

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”
    }
  ]
}
```