# Encryption APIs

_Use Evervault's Encrypt, Decrypt, and Fingerprint APIs to encrypt and decrypt data directly, and retrieve metadata for encrypted values._

Evervault provides APIs for encrypting and decrypting data. You can also retrieve metadata about encrypted values after they're encrypted with Evervault.

- The [Encrypt](#encrypt) endpoint allows you to encrypt a JSON value or file.
- The [Decrypt](#decrypt) endpoint allows you to decrypt a JSON value or file.
- The [Fingerprint](#fingerprint) endpoint allows you to retrieve metadata for an encrypted value.

## Encrypt

Use the [Encrypt API](/api#encrypt) to encrypt JSON values or files. For JSON, set the `Content-Type` header to `application/json` (use `application/octet-stream` for files). The request body can be any valid JSON type (a dictionary, array, number, boolean, or string). When passing strings, you need to enclose them in double quotes.

```javascript
const response = await fetch("https://api.evervault.com/encrypt", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    phoneNumber: "555-2368",
  }),
});
```

The response mirrors the shape of the request, with each value replaced by its encrypted form.

```json
{
  "phoneNumber": "ev:debug:Tk9D:GWgxSXezEFNw10b/:A6JZWe29uiZpP72w+nc0RXOdWdvgCulNqJv8aJpLE/gH:3V/PD54obBv0j+EJMaNNa/ny2tmZq7QM:$"
}
```

## Decrypt

Use the [Decrypt API](/api#decrypt) to decrypt JSON values or files. Values that aren't encrypted are returned unchanged.

> Be careful decrypting sensitive data within your infrastructure. It could impact your compliance scope or introduce security risks. You can optionally turn on PCI mode for your app to disable the Decrypt API. If you need to share sensitive data with partners, try using [Relay](/relay) instead.

```javascript
const response = await fetch("https://api.evervault.com/decrypt", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    phoneNumber:
      "ev:debug:Tk9D:GWgxSXezEFNw10b/:A6JZWe29uiZpP72w+nc0RXOdWdvgCulNqJv8aJpLE/gH:3V/PD54obBv0j+EJMaNNa/ny2tmZq7QM:$",
  }),
});
```

The response mirrors the shape of the request, with each encrypted value replaced by its decrypted form.

```json
{
  "phoneNumber": "555-2368"
}
```

## Fingerprint

Use the [Fingerprint API](/api#fingerprint) to retrieve metadata about an encrypted value. For example, if you pass an encrypted card, you can retrieve the card brand, the last four digits, etc.

```javascript
const response = await fetch("https://api.evervault.com/fingerprint", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    token:
      "ev:debug:Tk9D:HBpzdbFWXbX/N2cC:AyjMY/SKO49SlkXcDPtCGs+DxnUn/F8/lAtajCYZ/xT7:KV7AUn9vJJkZDtL8PKdOc8Y11yTL2vZQasFuHqM=:$",
  }),
});
```

The API responds with an object containing details about the encrypted data, as well as the card metadata inside of the `metadata` field.

```json
{
  "type": "string",
  "category": "card-number",
  "encryptedAt": 1700067122000,
  "role": null,
  "fingerprint": "u0ljSwrqhhUv7GykyCHB/A2bgVGXq06fnG9bOI27Sbg/tAOz3myr5zsfbasEWuMLiH6jZayu3AHGfiB7l+Bbjg",
  "metadata": {
    "bin": "424242",
    "lastFour": "4242",
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "gb",
    "currency": "gbp",
    "issuer": "Gringotts Wizarding Bank and Trust Company"
  }
}
```

### BIN Lookup vs. Fingerprint

| Metadata | Description | Fingerprint | BIN Lookup |
| --- | --- | --- | --- |
| Fingerprint | A unique identifier for the encrypted card. This can be used to detect card reuse. | ✓ | ✗ |
| BIN | The first 6 or 8 digits of the card number. | ✓ | ✗ |
| Last 4 | The last 4 digits of the card number. | ✓ | ✗ |
| Brand | The card brand, such as Visa or Mastercard. | ✓ | ✓ |
| Funding | The card funding type specifies the method by which transactions are financed (e.g. debit, credit). | ✓ | ✓ |
| Segment | The card segment indicates the primary market or usage category of the card (e.g. consumer, etc.). | ✓ | ✓ |
| Country | The country where the card was issued. | ✓ | ✓ |
| Currency | The currency of the card. | ✓ | ✓ |
| Issuer | The name of the card issuer. | ✓ | ✓ |
| Product Name | The name of the card product. | ✗ | ✓ |
| Fast Funds | Indicates whether the card supports fast funds (e.g. domestic, cross-border). | ✗ | ✓ |
| Match Precision | Indicates how many leading digits of the submitted BIN are confirmed by the matched data. A higher value means a more specific match. When multiple matches are found, the value represents the least precise BIN range the submitted BIN could belong to. | ✗ | ✓ |
| Three DS | Details on supported 3D Secure versions and ACS indicators for the card range. | ✗ | ✓ |

See [BIN Lookup](/cards/insights-and-verification#bin-lookup) for retrieving metadata for a BIN range instead of a single encrypted card.

- [Relay](/relay): Learn how to use Relay to encrypt or decrypt data in transit, without changing your application code.
- [Functions](/functions): Learn how to use Functions to process encrypted data with your own code.