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

JavaScript

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#

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TokenizeApi(config);
var body = new {
    first_name = "John",
    last_name = "Doe"
};

Object result = apiInstance.Tokenize(body);

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Map;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<API_KEY>");

        TokenizeApi apiInstance = new TokenizeApi(defaultClient);
        Object result = apiInstance.tokenize(Map.of(
                "first_name", "John",
                "last_name", "Doe"));
    }
}

Python

import basistheory
from basistheory.api import tokenize_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<API_KEY>")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body={
      "first_name": "John",
      "last_name": "Doe"
    })

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<API_KEY>"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "first_name": "John",
    "last_name": "Doe",
  }).Execute()
}

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

JavaScript

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#

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TokenizeApi(config);
var body = new Token
{
    Type = "token",
    Data = "Sensitive Value",
    Metadata = new Dictionary<string, string>
    {
        { "nonSensitiveField", "Non-Sensitive Value" }
    },
    SearchIndexes = new List<string>
    {
        "{{ data }}"
    },
    FingerprintExpression = "{{ data }}"
};

Object result = apiInstance.Tokenize(body);

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Arrays;
import java.util.Map;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<API_KEY>");

        TokenizeApi apiInstance = new TokenizeApi(defaultClient);
        Object result = apiInstance.tokenize(new Token()
                .type("token")
                .data("Sensitive Value")
                .metadata(Map.of("nonSensitiveField",  "Non-Sensitive Value"))
                .searchIndexes(Arrays.asList("{{ data }}"))
                .fingerprintExpression("{{ data }}"));
    }
}

Python

import basistheory
from basistheory.api import tokenize_api
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<API_KEY>")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body=Token(
      type="token",
      data="Sensitive Value",
      metadata={
        "nonSensitive": "Non-Sensitive Value"
      },
      search_indexes=[
        "{{ data }}"
      ],
      fingerprint_expression="{{ data }}"
    ))

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<API_KEY>"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "type": "token",
    "data": "Sensitive Value",
    "metadata": map[string]interface{}{
      "nonSensitiveField": "Non-Sensitive Value",
      },
    "search_indexes": []string{"{{ data }}"},
    "fingerprint_expression": "{{ data }}",
  }).Execute()
}

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

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

JavaScript

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#

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TokenizeApi(config);
var body = new Token {
    Type = "card",
    Data = new {
        number = "4242424242424242",
        expiration_month = 12,
        expiration_year = 2025,
        cvc = "123"
    },
    Metadata = new Dictionary<string, string> {
        { "nonSensitiveField",  "Non-Sensitive Value" }
    }
};

Object result = apiInstance.Tokenize(body);

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Map;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<API_KEY>");

        TokenizeApi apiInstance = new TokenizeApi(defaultClient);
        Object result = apiInstance.tokenize(new Token()
                .type("card")
                .data(Map.of("number", "4242424242424242",
                "expiration_month", 12,
                "expiration_year", 2025,
                "cvc", "123"))
                .metadata(Map.of("nonSensitiveField",  "Non-Sensitive Value")));
    }
}

Python

import basistheory
from basistheory.api import tokenize_api
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<API_KEY>")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body=Token(
      type="card",
      data={
          "number": "4242424242424242",
          "expiration_month": 12,
          "expiration_year": 2025,
          "cvc": "123"
      },
      metadata={
        "nonSensitive": "Non-Sensitive Value"
      }
    ))

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<API_KEY>"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "type": "card",
    "data": map[string]interface{}{
      "number":           "4242424242424242",
      "expiration_month": 12,
      "expiration_year":  2025,
      "cvc":              "123",
    },
    "metadata": map[string]interface{}{
      "nonSensitiveField": "Non-Sensitive Value",
    },
  }).Execute()
}

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

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

JavaScript

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#

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TokenizeApi(config);
var body = new object[] {
    "John",
    "Doe",
    new Token {
        Type = "card",
        Data = new {
            number = "4242424242424242",
            expiration_month = 12,
            expiration_year = 2025,
            cvc = "123"
        }
    },
    new Token {
        Type = "token",
        Data = "Sensitive Value"
    }
};

Object result = apiInstance.Tokenize(body);

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Arrays;
import java.util.Map;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<API_KEY>");

        TokenizeApi apiInstance = new TokenizeApi(defaultClient);
        Object result = apiInstance.tokenize(Arrays.asList(
                Arrays.asList("John", "Doe"),
                new Token()
                .type("card")
                .data(Map.of("number", "4242424242424242",
                "expiration_month", 12,
                "expiration_year", 2025,
                "cvc", "123"))
                .metadata(Map.of("nonSensitiveField",  "Non-Sensitive Value")),
                new Token()
                .type("token")
                .data("Sensitive Value")));
    }
}

Python

import basistheory
from basistheory.api import tokenize_api
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<API_KEY>")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

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

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<API_KEY>"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "first_name": "John",
    "last_name":  "Doe",
    "card_token": map[string]interface{}{
      "type": "card",
      "data": map[string]interface{}{
        "number":           "4242424242424242",
        "expiration_month": 12,
        "expiration_year":  2025,
        "cvc":              "123",
      },
      "metadata": map[string]interface{}{
        "nonSensitiveField": "Non-Sensitive Value",
      },
    },
    "generic_token": map[string]interface{}{
      "type": "token",
      "data": "Sensitive Value",
    },
  }).Execute()
}

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

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

JavaScript

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#

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TokenizeApi(config);
var body = new {
    first_name = "John",
    last_name = "Doe",
    primary_card = new Token {
        Type = "card",
        Data = new {
            number = "4242424242424242",
            expiration_month = 12,
            expiration_year = 2025,
            cvc = "123"
        }
    },
    sensitive_tags = new object[] {
        "preferred",
        new Token {
            Type = "token",
            Data = "vip"
        }
    }
};

Object result = apiInstance.Tokenize(body);

Python

import basistheory
from basistheory.api import tokenize_api
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<API_KEY>")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body={
        "first_name": "John",
        "last_name": "Doe",
        "primary_card": Token(
            type="card",
            data={
                "number": "4242424242424242",
                "expiration_month": 12,
                "expiration_year": 2025,
                "cvc": "123"
            }),
        "sensitive_tags": [
            "preferred",
            {
                "type": "token",
                "data": "vip"
            }
        ]
    })

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<API_KEY>"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "first_name": "John",
    "last_name":  "Doe",
    "primary_card": map[string]interface{}{
      "type": "card",
      "data": map[string]interface{}{
        "number":           "4242424242424242",
        "expiration_month": 12,
        "expiration_year":  2025,
        "cvc":              "123",
      },
    },
    "sensitive_tags": map[string]interface{}{
      "preferred",
      map[string]interface{}{
          "type": "token",
          "data": "vip"
      },
    },
  }).Execute()
}

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