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 100.

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.

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.Tokenize;

var client = new TokenizeClient("<API_KEY>");

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

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.Tokenize;

var client = new TokenizeClient("<API_KEY>");

var token = await client.TokenizeAsync(new Token {
  Type = "token",
  Data = "Sensitive Value",
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField",  "Non-Sensitive Value" }
  },
  SearchIndexes = new List<string> {
    "{{ data }}"
  },
  FingerprintExpression = "{{ data }}"
});

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_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.Tokenize;

var client = new TokenizeClient("<API_KEY>");

var token = await client.TokenizeAsync(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" }
  }
});

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_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.Tokenize;

var client = new TokenizeClient("<API_KEY>");

var token = await client.TokenizeAsync(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"
  }
});

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_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.Tokenize;

var client = new TokenizeClient("<API_KEY>");

var token = await client.TokenizeAsync(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"
    }
  }
});

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