# Insights

_Use Evervault Inspect and BIN Lookup APIs to retrieve rich metadata for card numbers._

![An illustration of a BIN being searched in a database]()

The Evervault API provides several endpoints which can be used to retrieve additional information for cards and bin ranges. This can be used for tasks such as fraud detection and payment routing.

- The [Inspect](#inspect) endpoint allows you to retrieve metadata for an encrypted card number.
- The [BIN Lookup](#bin-lookup) endpoint allows you to retrieve metadata for a BIN range.
- The [CardInsights](#card-insights) endpoint allows you to perform cardholder verification checks and enrichment.

## Inspect

The [Inspect](/api#inspect) endpoint allows you to retrieve metadata for an encrypted card. This can be used to retrieve information such as the card brand, the last four digits, and more.

To retrieve metadata for an encrypted card, send the encrypted card number to the [Inspect](/api#inspect) API endpoint. The API key and app ID are required to authenticate the request, and the API key needs the `api:inspect` permission.

```javascript
const response = await fetch("https://api.evervault.com/payments/inspect", {
  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 will respond 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

The [BIN Lookup API](/api#createBinLookup) allows you to retrieve BIN data for a card number or BIN range. You can pass a plaintext card number, an encrypted card number, or the first 6-10 digits of a card number. If the number matches a range of BINs, the response returns metadata that is common to all the BINs in that range. The API key and app ID are required to authenticate the request, and the API key needs the `binLookup:create` permission.

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

The response includes the BIN metadata, such as the card brand, the funding type, the country, and other relevant details.

```json
{
  "id": "bin_lookup_1234567890",
  "brand": "visa",
  "funding": "credit",
  "segment": "consumer",
  "country": "gb",
  "currency": "gbp",
  "issuer": "Gringotts Wizarding Bank and Trust Company",
  "type": "card",
  "productName": "Visa Wizard",
  "fastFunds": {
    "domestic": true,
    "crossBorder": true
  },
  "threeDS": {
    "supportedVersions": {
      "accessControlServer": ["2.2.0"],
      "directoryServer": ["2.2.0", "2.3.1"]
    },
    "acsInfoIndicators": [
      {
        "code": "acs-auth-available",
        "indicator": "01",
        "description": "Authentication Available at ACS"
      }
    ]
  },
  "createdAt": 169297262323
}
```

### BIN Lookup vs Inspect

| Metadata | Description | Inspect | 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). | ✗ | ✓ |
| Three DS | Details on supported 3D Secure versions and ACS indicators for the card range. | ✗ | ✓ |

## Card Insights

> **Beta**
>
> The Card Insights API is currently in Beta for customers on custom plans. Please
>   contact us at
>   <a href="mailto:support@evervault.com">support@evervault.com</a> for more information.

The [Card Insights API](/api#createCardInsight) provides a powerful, real-time interface for card and cardholder verification checks and enrichment. It allows you to run address verification (AVS), cardholder name verification (ANI), and CVV validation. You can also retrieve BIN information and the push and pull transaction capabilities for disbursements and collections. By unifying these inputs, the API provides real-time assessments of card and cardholder authenticity alongside rich card metadata—enabling precise validation and smarter routing, handling, and fraud prevention.

### Creating a card insight

Card Insights is extensible - you choose the insights you need per request. Every response includes BIN data by default. You can add any of the following extensions:

1. **Address Verification (AVS)** – Run AVS to verify postal code and street-level elements (line1, line2, city, state, country) against issuer records.
2. **Name Verification** – Run ANI to verify the provided first and last name against issuer records.
3. **Transaction Capabilities** – Determine push and pull transaction eligibility, network, regulatory status, and expected funds-availability windows.
4. **CVV Validation** – Validate the CVV against issuer records.

This example requests all possible extensions and includes both required and optional fields. The example response includes all possible fields.

```javascript
const response = await fetch("https://api.evervault.com/insights/cards", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    card: {
      number: "4111111111111111",
      cvv: "123",
      expiry: {
        month: "12",
        year: "29",
      },
    },
    extensions: ["capabilities", "address", "cardholder", "cvv"],
    address: {
      postalCode: "10001",
      line1: "Main Street",
      line2: "Anytown",
      city: "New York",
      state: "NY",
      country: "us",
    },
    cardholder: {
      firstName: "John",
      lastName: "Doe",
    },
  }),
});
```

### Extensions & Required fields

| Extension | Required Fields |
| --- | --- |
| `capabilities` | `card.number` |
| `address` | `card.number`, `card.expiry`, `address.postalCode` |
| `cardholder` | `card.number`, `card.expiry`, `cardholder.firstName`, `cardholder.lastName` |
| `cvv` | `card.number`, `card.expiry`, `card.cvv` |

### Request validation rules

There are some general rules that need to be followed for all strings fields. Failure to follow these will result in an error.

- All string fields must only consist of ASCII characters.
- Consecutive periods (`.`) will result in an error.

The following characters are restricted for all string fields:

| Forbidden Character | Description |
| --- | --- |
| `\` | Backslash |
| `^` | Caret |
| `,` | Comma |
| `"` | Double Quotes |
| `()` | Parentheses |
| `\|` | Pipe |
| `;` | Semi-Colon |
| `~` | Tilde |

#### Card fields:

- The `number` must be a valid card number (either in plaintext for as an Evervault encrypted string).
- The `cvv` must be a valid CVV for the given card brand.
- The `month` and `year` for the `expiry` must be 2 digit strings.

#### Transaction fields:

- The `amount` must be a number.
- The `currency` must be a valid ISO-4217 three digit currency code.

#### Cardholder fields:

For name fields there are additional character restrictions. These are outlined below. Failure to remove these will result in an error.

| Forbidden Name Field Character | Description |
| --- | --- |
| `&` | Ampersand |
| `$` | Dollar Sign |
| `=` | Equal Sign |
| `!` | Exclamation Mark |
| `/` | Forward Slash |
| `#` | Hash / Pound |
| `%` | Percent |
| `+` | Plus |
| `?` | Question mark |
| `_` | Underscore |

#### Address fields:

- If no `country` is provided, then it defaults to `us`.
- If the country is `us` (United States) then the `postalCode` must be a 5 or 9 digit string. The hyphen must be exluded.
- If the country is `ca` (Canada) then the `postalCode` must follow the Candadian postal code format (ANA NAN) e.g. `A1A 1A1`. The space character must be included.
- The `state` must be a valid ISO-3166 subdivision code. e.g `ny` for New York.
- The `country` must be a valid ISO-3166 two character country code.

- [Card Collection](/cards/card-collection): Learn how to use Card Collection to collect cardholder data.
- [Network Tokens](/cards/network-tokens): Learn how to use Network Tokens to enhance your payment security.