Skip to main content

Tokenize

The tokenize endpoint enables you to tokenize any request and tokenize several types of tokens in the same request. It can be utilized to combine multiple API calls into a single request to match your current data structure or bulk token creation.

The maximum number of tokens that can be created within a single request is defined by your Tenant's "Tokenize Limit" Quota.

POST
https://api.basistheory.com/tokenize
Copy

Permissions

token:create

The token:create permission must be granted on each destination container, and the required scope of this permission is determined by the containers specified in the tokenize request.

For security reasons, the data and metadata attributes are redacted from the response when a token is deduplicated, unless the API Key has token:read permission in the targeted container. Click here to learn more about this behavior.

Create Basic Token

Request

curl "https://api.basistheory.com/tokenize" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"first_name": "John",
"last_name": "Doe"
}'

Response

{
"first_name": "b0804096-5a47-4b8c-8fb7-b9ecc5e72eec",
"last_name": "814a6416-3410-4224-8ea9-c0b4d453c9ce"
}

Create Token

Request

curl "https://api.basistheory.com/tokenize" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"type": "token",
"data": "Sensitive Value",
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
},
"search_indexes": [ "{{ data }}" ],
"fingerprint_expression": "{{ data }}"
}'

Response

{
"id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"type": "token",
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
},
"search_indexes": ["{{ data }}"],
"fingerprint": "AKCUXS83DokKo4pDRKSAy4d42t9i8dcP1X2jijwEBCQH",
"fingerprint_expression": "{{ data }}",
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00"
}

Create Card

Request

curl "https://api.basistheory.com/tokenize" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"type": "card",
"data": {
"number": "4242424242424242",
"expiration_month": 12,
"expiration_year": 2025,
"cvc": "123"
},
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
}
}'

Response

{
"id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"type": "card",
"mask": {
"number": "XXXXXXXXXXXX4242",
"expiration_month": 12,
"expiration_year": 2025
},
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
},
"fingerprint": "AKCUXS83DokKo4pDRKSAy4d42t9i8dcP1X2jijwEBCQH",
"fingerprint_expression": "{{ data.number }}",
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00"
}

Tokenize Array

Request

curl "https://api.basistheory.com/tokenize" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '[
"John",
"Doe",
{
"type": "card",
"data": {
"number": "4242424242424242",
"expiration_month": 12,
"expiration_year": 2025,
"cvc": "123"
}
},
{
"type": "token",
"data": "Sensitive Value"
}
]'

Response

[
"b0804096-5a47-4b8c-8fb7-b9ecc5e72eec",
"814a6416-3410-4224-8ea9-c0b4d453c9ce",
{
"id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"type": "card",
"data": {
"number": "XXXXXXXXXXXX4242",
"expiration_month": 12,
"expiration_year": 2025
},
"fingerprint": "AKCUXS83DokKo4pDRKSAy4d42t9i8dcP1X2jijwEBCQH",
"fingerprint_expression": "{{ data.number }}",
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00"
},
{
"id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"type": "token",
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00"
}
]

Composite

Request

curl "https://api.basistheory.com/tokenize" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"first_name": "John",
"last_name": "Doe",
"primary_card": {
"type": "card",
"data": {
"number": "4242424242424242",
"expiration_month": 12,
"expiration_year": 2025,
"cvc": "123"
}
},
"sensitive_tags": [
"preferred",
{
"type": "token",
"data": "vip"
}
]
}'

Response

{
"first_name": "b0804096-5a47-4b8c-8fb7-b9ecc5e72eec",
"last_name": "814a6416-3410-4224-8ea9-c0b4d453c9ce",
"primary_card": {
"id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"type": "card",
"data": {
"number": "XXXXXXXXXXXX4242",
"expiration_month": 12,
"expiration_year": 2025
},
"fingerprint": "AKCUXS83DokKo4pDRKSAy4d42t9i8dcP1X2jijwEBCQH",
"fingerprint_expression": "{{ data.number }}",
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00"
},
"sensitive_tags": [
"be3dff7a-4e01-4a52-93e6-9f8ef03f3cd9",
{
"id": "aaed779a-3152-437d-8e8a-10afeb0fe620",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"type": "token",
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00"
}
]
}