Search Tokens
Enterprise

Most tokens will be searchable within seconds, although it may take up to a few minutes.

Search for tokens using a Lucene-based query syntax.

Search v2

POST

https://api.basistheory.com/v2/tokens/search

Permissions

token:search

Request

curl "https://api.basistheory.com/v2/tokens/search" \
-H "BT-API-KEY: <PRIVATE_API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
  "query": "data:6789",
  "size": 20
}'

const response = await client.tokens.searchV2();
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
const page = await client.tokens.searchV2();
while (page.hasNextPage()) {
    page = page.getNextPage();
}

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

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

const tokens = await bt.tokensV2.search({
  query: "data:6789",
  size: 20,
});

await client.Tokens.SearchV2Async(new SearchTokensRequestV2());

response = client.tokens.search_v2()

for item in response:
    yield item

# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

Request Parameters

Attribute	Required	Type	Default	Description
`query`	false	string	`null`	A query string using Lucene query syntax. Only a single search term is supported.
`start`	false	string	`null`	Cursor provided in the previous query to get the next set of results.
`size`	false	integer	`20`	Number of results per page to return. Maximum size of 100 results.

Response

Returns a cursor paginated object with the data property containing an array of tokens sorted by container and created_at, descending. Token data will be returned according to the transform applied to the requesting Application's Access Controls. Returns an error if tokens could not be retrieved or when an invalid query is submitted.

{
  "pagination": {
    "page_size": 20,
    "next": "AgAAAA=="
  },
  "data": [
    {
      "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
      "type": "social_security_number",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "XXX-XX-6789",
      "fingerprint": "AKCUXS83DokKo4pDRKSAy4d42t9i8dcP1X2jijwEBCQH",
      "containers": ["/pii/high/"],
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "search_indexes": [
        "{{ data }}",
        "{{ data | replace: '-' }}",
        "{{ data | last4 }}"
      ],
      "fingerprint_expression": "{{ data }}",
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

Supported Queries (v2)

Supported Fields

Fields	Type	Description	Example
`container`	string	Filters the results to only include tokens within the given container, or its child containers.	`container:\"/pci/\"`
`type`	string	Filters the results to only include tokens of the given type.	`type:card`
`fingerprint`	string	Filters the results to only include tokens with the given fingerprint.	`fingerprint:BzQfn8W5PTjHMZgmJfbTjN`
`metadata.[key]`	string	Filters the results to only include tokens with the given metadata key and value.	`metadata.user_id:34445`
`data`	string	Filters the results to only include tokens that have been indexed with the given data value. See Searching Data for details.	`data:6789`

Behavior

Each supported field can appear at most once within a query.
The container field can be combined with other supported fields with an AND operator.
- This can be used to limit the scope of the search to a single container and its child containers.
- If container is specified, the application must have token:search permission to the given container.
- If container is not specified, the response will include tokens from all containers the application has token:search permission to.
Except for container, the AND operator cannot be used to combine terms for multiple fields in the same query.
Metadata will be searched for a case-sensitive, exact match on both key and value.

Search v1
DEPRECATED

POST

https://api.basistheory.com/tokens/search

Permissions

token:search

Request

curl "https://api.basistheory.com/tokens/search" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "query": "data:6789",
    "page": 1,
    "size": 20
  }'

const response = await client.tokens.search();
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
const page = await client.tokens.search();
while (page.hasNextPage()) {
    page = page.getNextPage();
}

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

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

const tokens = await bt.tokens.search({
  query: "data:6789",
  page: 1,
  size: 20,
});

await client.Tokens.SearchAsync(new SearchTokensRequest());

response = client.tokens.search()

for item in response:
    yield item

# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

Request Parameters

Attribute	Required	Type	Default	Description
`query`	false	string	`null`	A query string using Lucene query syntax. Only a single search term is supported.
`page`	false	integer	`1`	Page number of the results to return.
`size`	false	integer	`20`	Number of results per page to return. Maximum size of 100 results.

Response

Returns a paginated object with the data property containing an array of tokens sorted by created_at, descending. Token data will be returned according to the transform applied to the requesting Application's Access Controls. Returns an error if tokens could not be retrieved or when an invalid query is submitted.

{
  "pagination": {...},
  "data": [
    {
      "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
      "type": "social_security_number",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "XXX-XX-6789",
      "fingerprint": "AKCUXS83DokKo4pDRKSAy4d42t9i8dcP1X2jijwEBCQH",
      "containers": ["/pii/high/"],
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "search_indexes": [
        "{{ data }}",
        "{{ data | replace: '-' }}",
        "{{ data | last4 }}"
      ],
      "fingerprint_expression": "{{ data }}",
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

Supported Queries (v1)

Supported Fields

Fields	Type	Description	Example
`id`	string	Token ID.	`id:fe24d4cc-de50-4d8c-8da7-8c7483ba21bf`
`data`	string	Token data. See Searching Data for supported values.	`data:6789`
`metadata.[key]`	string	Search against token metadata having the given `[key]`.	`metadata.user_id:34445`

Behavior

Combining terms for multiple token fields in the same query is not supported.
Multiple metadata fields may be combined within the same query with an AND operator.
Metadata will be searched for a case-insensitive, exact match on both key and value.

Query Syntax

Token search supports a Lucene-based query syntax. A query string is comprised of one or more Terms that can be combined with AND Operators.

Search terms are formed by combining a field name and a value to search with a : - field:value.

Token data may be searched on search indexed tokens by performing a case-sensitive exact match to one of several indexed data patterns. For example, the following query will search for indexed tokens containing the data 123-45-6789:

  data:123-45-6789

Phrases or values containing spaces may be searched by wrapping the searched value in quotes, for example:

  data:"data containing multiple words"

For more detailed information about supported data searches, see Searching Data.

Metadata search terms require both a key and value to be specified in the form of metadata.[key]:value. For example, to search for tokens having the metadata { customer_id: "cus_12345" }, query for:

  metadata.customer_id:cus_12345

See the Supported Queries (v2) and Supported Queries (v1) sections above for further details and a complete list of supported fields.

Searching Data

Basis Theory supports search across sensitive token data by securely creating and storing search indexes at the time of token creation. To index a token for data search, one or more search_indexes can be specified in the Create Token Request or Tokenize Request. Some token types will receive a default set of search indexes if custom search_indexes are not specified on the request.

The search_indexes property supports the use of expressions, which are based on the Liquid templating language. Each expression must result in a single value, which cannot be null or empty, otherwise a 400 error will be returned.

Any expressions contained within search_indexes will be evaluated against the token data before generating indexes. Token data searches will only return a token if there is an exact match on one of the evaluated search_indexes.

For example, if a card token has the number 4242424242424242 and it is created with the search index expressions:

{{ data.number }}
{{ data.number | last4 }}

Then you may search for this token by querying on either the full card number:

  data:4242424242424242

or by querying on the last 4 digits:

  data:4242

Search v2​

Permissions​

Request​

Request Parameters​

Response​

Supported Queries (v2)​

Supported Fields​

Behavior​

Search v1 DEPRECATED​

Permissions​

Request​

Request Parameters​

Response​

Supported Queries (v1)​

Supported Fields​

Behavior​

Query Syntax​

Searching Data​

Search v2

Permissions

Request

Request Parameters

Response

Supported Queries (v2)

Supported Fields

Behavior

Search v1
DEPRECATED

Permissions

Request

Request Parameters

Response

Supported Queries (v1)

Supported Fields

Behavior

Query Syntax

Searching Data