# Insights and Verification

_Use Evervault's Insights and Verification APIs to retrieve rich metadata for card numbers._

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

The Evervault API provides several endpoints that 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.

- Use the [Card Insights](#card-insights) endpoint to perform cardholder verification checks and enrichment.
- Use the [BIN Lookup](#bin-lookup) endpoint to retrieve metadata for a BIN range.
- Use the [PAR Lookup](#par-lookup) endpoint to retrieve the Payment Account Reference (PAR) for a card number or network token.

## 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)
- CVV validation
- Email and phone verification

You can also retrieve BIN information, the Payment Account Reference (PAR), and the push and pull transaction capabilities for disbursements and collections. Checks can run against either a card or a network token. 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

You can run Card Insights against either a card (PAN) or a network token. Provide exactly one of `card` or `networkToken` per request.

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 name (first, last, middle, suffix, and owner type) 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. Not available for network tokens.
5. **Email Verification** – Verify the provided email address against issuer records.
6. **Phone Verification** – Verify the provided phone number against issuer records.
7. **Payment Account Reference (PAR)** – Retrieve the Payment Account Reference for the card.

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",
      "email",
      "phone",
      "paymentAccountReference",
    ],
    address: {
      postalCode: "10001",
      line1: "Main Street",
      line2: "Anytown",
      city: "New York",
      state: "NY",
      country: "us",
    },
    cardholder: {
      firstName: "John",
      lastName: "Doe",
      middleName: "Michael",
      suffix: "Jr",
      ownerType: "01",
    },
    email: "john.doe@example.com",
    phone: "0016505551234",
  }),
});
```

Alternatively, provide a `networkToken` in place of `card`:

```javascript
body: JSON.stringify({
  networkToken: {
    number: "4111111111111111",
    cryptogram: "AgAAAAAABk4DdZzBRckAAAAA",
    expiry: {
      month: "12",
      year: "29",
    },
    // transactionIdentifier, brand, and funding are required for Amex and Discover
    transactionIdentifier: "1234567890",
    brand: "visa",
    funding: "credit",
  },
  extensions: ["capabilities", "address", "paymentAccountReference"],
  address: {
    postalCode: "10001",
    country: "us",
  },
});
```

### Extensions and 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` |
| `email` | `card.number`, `email` |
| `phone` | `card.number`, `phone` |
| `paymentAccountReference` | `card.number` |

> The `cvv` extension isn't available for network token lookups. For all other
>   extensions, replace the `card.*` requirements above with the equivalent
>   `networkToken.*` fields.

### 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

- `firstName` and `lastName` are required when the `cardholder` extension is requested.
- `middleName` and `suffix` are optional and refine the name match.
- `ownerType` is optional and indicates whether the cardholder is the primary (`01`) or secondary (`02`) account owner.

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 |

#### Email and phone fields:

Email and phone verification aren't widely supported by issuers, so coverage is limited.

- The `email` must be a valid email address. Required when the `email` extension is requested.
- The `phone` must be in IDD-prefixed E.164 format: E.164 international format with the `00` IDD prefix substituted for `+` (for example `0016505551234` for a US number). Required when the `phone` extension is requested.

#### Network token fields:

- The `number` must be a valid network token number (either in plaintext or as an Evervault encrypted string).
- The `cryptogram` must be a valid cryptogram (either in plaintext or as an Evervault encrypted string).
- The `month` and `year` for the `expiry` must be 2 digit strings.
- `transactionIdentifier`, `brand`, and `funding` are required for Amex and Discover network tokens.

#### 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 excluded.
- If the country is `ca` (Canada) then the `postalCode` must follow the Canadian 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.

## 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
  },
  "matchPrecision": 8,
  "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
}
```

## PAR Lookup

> **Beta**
>
> PAR Lookup is in beta for customers on custom plans. [Contact Support](mailto:support@evervault.com) for more information. Visa, Mastercard, and Discover cards are currently supported.

The [PAR Lookup API](/api#createParLookup) returns the Payment Account Reference for a card number or network token. A PAR is a stable identifier the card network assigns to a card. Unlike a card number, it stays constant when a card is reissued, renewed, or replaced, and every network token derived from the card resolves to the same PAR.

This makes PAR useful for identifying when a network token and a physical card are the same underlying payment account. You can use the PAR to track a card across reissues, and linking its activity to a single cardholder for fraud detection or lifetime-value analysis.

> **Card and account identifiers**
>
> A PAR identifies a card and its tokens over time, not the underlying bank account or the cardholder. Distinct cards on the same account aren't guaranteed to share a PAR.

To look up a PAR, send a plaintext or Evervault-encrypted card number or network token to the PAR Lookup endpoint. The API key and app ID are required to authenticate the request, and the API key needs the `parLookup:create` permission.

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

The response includes the resolved PAR, along with an identifier for the lookup.

```json
{
  "id": "par_lookup_1234567890",
  "paymentAccountReference": "5001BN2CUZCOY2H2IJILTJJZWTEPW"
}
```

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