Skip to main content

Send Data to a 3rd Party

This guide will show you how to send data to a third-party service without touching the data.

Key concepts in this guide:

Getting Started​

To get started, you will need a Basis Theory account.

Next you will need a Private Application in order to create a new token and use the token with the Proxy.

Click here to create a Private Application or login to your Basis Theory account and create a new application with the following settings:

  • Name - Send Data to Third Party Guide
  • Application Type - Private
  • Permissions - token:create, token:use
Save the API Key from the created Private Application as it will be used later in this guide to capture the data and send it to a third-party.

Create a Token​

We will need to create a token to contain our data. Basis Theory offers several ways to capture this information from your web application or inbound to your API without touching the information, but for this guide, we will create the token directly against the Basis Theory API.

Run the following in your terminal to create a token containing a phone number:

curl "https://api.basistheory.com/tokens" \
-X "POST" \
-H "BT-API-KEY: test_1234567890" \
-H "Content-Type: application/json" \
-d '{
    "type": "token",
    "data": "(555) 687-5309"
}'
Be sure to replace test_1234567890 with the Private API Key you created in the Getting Started step.

You should see a JSON response similar to:

{
  "id": "d2411dd4-17f0-47ce-a4e2-78a66f2e4606",
  "type": "token",
  "tenant_id": "4d228c59-13e9-4d26-9ff3-883336579d35",
  "created_by": "59929b69-1282-43e1-8b26-8cf655964f9b",
  "created_at": "2022-12-19T19:20:43.7334616+00:00",
  "privacy": {
    "classification": "general",
    "impact_level": "high",
    "restriction_policy": "redact"
  },
  "search_indexes": [],
  "containers": [
    "/general/high/"
  ]
}

Copy the id to use in the next step.

It is best practice to securely collect your data from a web form or API to avoid security and compliance risks associated with directly handling the sensitive data.

Send the Data​

We can leverage the Basis Theory Ephemeral Proxy to detokenize the stored data before forwarding it to a third-party. To do this, we will utilize Expressions, which are based on the Liquid template language.

curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: test_1234567890' \
-H 'BT-PROXY-URL: https://echo.basistheory.com/anything' \
-H 'Content-Type: application/json' \
-d '{
      "phoneNumber": {
        "full": "+1 {{ d2411dd4-17f0-47ce-a4e2-78a66f2e4606 }}",
        "countryCode": "+1",
        "areaCode": "{{ d2411dd4-17f0-47ce-a4e2-78a66f2e4606 | split: \" \" | first | remove: \"(\" | remove: \")\" }}",
        "exchangeCode": "{{ d2411dd4-17f0-47ce-a4e2-78a66f2e4606  | split: \"-\" | last }}",
        "lineNumber": "{{ d2411dd4-17f0-47ce-a4e2-78a66f2e4606 | split: \" \" | last | split: \"-\" | first }}"
      }
    }'
Be sure to replace test_1234567890 with the Private API Key you created in the Getting Started step and replace d2411dd4-17f0-47ce-a4e2-78a66f2e4606 with the token id you created in the Create a Token step.

You should see a response similar to:

{
  "args": {},
  "data": "{\"phoneNumber\":{\"full\":\"+1 (555) 687-5309\",\"countryCode\":\"+1\",\"areaCode\":\"555\",\"exchangeCode\":\"5309\",\"lineNumber\":\"687\"}}",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Accept-Encoding": "gzip",
    "Bt-Trace-Id": "0kr2gYwAAAACKcnGsnP/NTrEa4nIHenpYQ0hHRURHRTE1MTAAMTYzY2E1ODMtNjQ3MS00MTc3LTg0ZGItZTA4MzBlZGFiODUw",
    "Content-Length": "125",
    "Content-Type": "application/json",
    "Disguised-Host": "echo.basistheory.com",
    "Host": "echo.basistheory.com",
    "Max-Forwards": "10",
    "User-Agent": "curl/7.85.0"
  },
  "json": {
    "phoneNumber": {
      "full": "+1 (555) 687-5309",
      "countryCode": "+1",
      "areaCode": "555",
      "exchangeCode": "5309",
      "lineNumber": "687"
    }
  },
  "method": "POST",
  "url": "https://echo.basistheory.com/anything"
}

Conclusion​

Basis Theory's Proxy will intercept the request to evaluate and detokenize expressions within the request body. Basis Theory will then forward the request onto the configured BT-PROXY-URL, which in this example is https://echo.basistheory.com/anything.

You can use this guide as an example of how to easily forward any piece of information and transform the request prior to sending to the destination.

Learn More​