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.

If a request contains multiple tokens and one token is invalid, the entire request will fail.

POST

https://api.basistheory.com/tokenize

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

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"
  }'

Node

await client.tokens.tokenize({
  "first_name": "John",
  "last_name": "Doe"
});

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const token = await bt.tokenize({
  first_name: "John",
  last_name: "Doe",
});

C#

await client.Tokens.TokenizeAsync(new
  {
    first_name = "John",
    last_name = "Doe",
  });

Java

Python

client.tokens.tokenize(
    request={
        "first_name": "John",
        "last_name": "Doe"
    }
)

Go

Response

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

Create Token

Request

cURL

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 }}"
  }'

Node

await client.tokens.tokenize({
  type: "token",
  data: "Sensitive Value",
  metadata: {
    "nonSensitive": "Non-Sensitive Value"
  },
  search_indexes: [
    "{{ data }}"
  ],
  fingerprint_expression: "{{ data }}"
});

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const token = await bt.tokenize({
  type: "token",
  data: "Sensitive Value",
  metadata: {
    nonSensitiveField: "Non-Sensitive Value",
  },
  search_indexes: ["{{ data }}"],
  fingerprint_expression: "{{ data }}",
});

C#

await client.Tokens.TokenizeAsync(new
{
  type = "token",
  data = "Sensitive Value",
  metadata = new {
    nonSensitive = "Non-Sensitive Value"
  },
  search_indexes = new []
  {
    "{{ data }}"
  },
  fingerprint_expression = "{{ data }}"
});

Java

Python

client.tokens.tokenize(
    request={
        "type": "token",
        "data": "Sensitive Value",
        "metadata": {
            "nonSensitive": "Non-Sensitive Value"
        },
        "search_indexes": [
            "{{ data }}"
        ],
        "fingerprint_expression": "{{ data }}"
    }
)

Go

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",
  "_extras": {
    "deduplicated": false
  }
}

Create Card

Request

cURL

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"
    }
  }'

Node

await client.tokens.tokenize({
  type: "card",
  data: {
    number: "4242424242424242",
    expiration_month: 12,
    expiration_year: 2025,
    cvc: "123",
  },
  metadata: {
    nonSensitiveField: "Non-Sensitive Value",
  },
});

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const token = await bt.tokenize({
  type: "card",
  data: {
    number: "4242424242424242",
    expiration_month: 12,
    expiration_year: 2025,
    cvc: "123",
  },
  metadata: {
    nonSensitiveField: "Non-Sensitive Value",
  },
});

C#

await client.Tokens.TokenizeAsync(new
{
  type = "card",
  data = new
  {
    number = "4242424242424242",
    expiration_month = 12,
    expiration_year = 2025,
    cvc = "123",
  },
  metadata = new
  {
    nonSensitiveField = "Non-Sensitive Value",
  }
});

Java

Python

client.tokens.tokenize(
    request={
        "type": "card",
        "data": {
            "number": "4242424242424242",
            "expiration_month": 12,
            "expiration_year": 2025,
            "cvc": "123"
        },
        "metadata": {
            "nonSensitive": "Non-Sensitive Value"
        }
    }
)

Go

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",
  "_extras": {
    "deduplicated": false
  }
}

Tokenize Array

Request

cURL

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"
    }
  ]'

Node

await client.tokens.tokenize([
  "John",
  "Doe",
  {
    type: "card",
    data: {
      number: "4242424242424242",
      expiration_month: 12,
      expiration_year: 2025,
      cvc: "123",
    },
    metadata: {
      nonSensitiveField: "Non-Sensitive Value",
    },
  },
  {
    type: "token",
    data: "Sensitive Value",
  },
]);

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const token = await bt.tokenize([
  "John",
  "Doe",
  {
    type: "card",
    data: {
      number: "4242424242424242",
      expiration_month: 12,
      expiration_year: 2025,
      cvc: "123",
    },
    metadata: {
      nonSensitiveField: "Non-Sensitive Value",
    },
  },
  {
    type: "token",
    data: "Sensitive Value",
  },
]);

C#

await client.Tokens.TokenizeAsync(new List<object>
{
  "John",
  "Doe",
  new {
    type = "card",
    data = new
    {
        number = "4242424242424242",
        expiration_month = 12,
        expiration_year = 2025,
        cvc = "123",
    },
    metadata = new
    {
      nonSensitiveField = "Non-Sensitive Value",
    }
  },
  new
  {
    type = "token",
    data = "Sensitive Value"
  }
});

Java

Python

client.tokens.tokenize(
    request=[
        "John",
        "Doe",
        {
            "type": "card",
            "data": {
                "number": "4242424242424242",
                "expiration_month": 12,
                "expiration_year": 2025,
                "cvc": "123"
            },
            "metadata": {
                "nonSensitive": "Non-Sensitive Value"
            }
        },
        {
            "type": "token",
            "data": "Sensitive Value"
        }
    ]
)

Go

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",
    "_extras": {
      "deduplicated": false
    }
  },
  {
    "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",
    "_extras": {
      "deduplicated": false
    }
  }
]

Composite

Request

cURL

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"
      }
    ]
  }'

Node

await client.tokens.tokenize({
  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",
    },
  ],
});

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const token = await bt.tokenize({
  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",
    },
  ],
});

C#

await client.Tokens.TokenizeAsync(new
{
  first_name = "John",
  last_name = "Doe",
  primary_card = new
  {
    type = "card",
    data = new {
      number = "4242424242424242",
      expiration_month = 12,
      expiration_year = 2025,
      cvc = "123"
    }
  },
  sensitive_tags = new object[]
  {
    "preferred",
    new
    {
      type = "token",
      data = "vip"
    }
  }
});

Python

client.tokens.tokenize(
    request={
        "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"
            }
        ]
    }
)

Go

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",
    "_extras": {
      "deduplicated": false
    }
  },
  "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",
      "_extras": {
        "deduplicated": false
      }
    }
  ]
}