---
title: "BIN API Reference — Endpoints, Fields & Errors"
description: "Complete BIN lookup REST API reference. POST /v1/bin endpoint, request parameters, JSON response fields, error codes, and code examples in 7 languages."
section: "API"
url: "https://binlookupapi.com/docs/api-reference/"
markdown_url: "https://binlookupapi.com/docs/api-reference.md"
---
# BIN Lookup API Reference

This page is the specification for the BIN Lookup API.

The base URL is `https://api.binlookupapi.com`. Send API requests to this host only. The dashboard host does not accept API requests.

| Method and path | Use |
|-----------------|-----|
| `POST /v1/bin` | Look up one BIN. This page documents this endpoint. |
| `POST /v1/bins` | Look up 1 to 2,000 BINs. See [Batch lookups](/docs/batch-lookups/). |

The machine-readable specification is the [OpenAPI file](https://app.binlookupapi.com/openapi.json). The API generates this file. Import it into Postman, Insomnia, or a code generator.

You can also fork the public Postman collection:

Language examples are in the [guides](/docs/guides/).

## Authentication

Send the API key in the `Authorization` header. Use the Bearer scheme.

```text
Authorization: Bearer YOUR_API_KEY
```

Create the key on the API Keys page. See [API keys](/docs/api-keys/).

| HTTP status | Error code | Cause |
|-------------|------------|-------|
| 401 | `UNAUTHORIZED` | The header is missing, or the key is not valid, revoked, or expired. |
| 403 | `FORBIDDEN` | The key does not have permission for this endpoint. |

## Look up one BIN

Send `POST /v1/bin` with a JSON body. The body has one field, `number`.

```bash
curl -X POST "https://api.binlookupapi.com/v1/bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": 42467101}'
```

```json
{ "number": 42467101 }
```

Rules for `number`:

- Send the first 6 to 11 digits of the card number.
- Send an integer from `100000` to `99999999999`.
- A string of digits is also accepted. The API converts it to an integer.
- Leading zeros are removed. `"04246710"` is the same value as `4246710`.
- The JSON body must be 1 KB or smaller.
- Do not send a full card number. See [Card numbers](/docs/support/security/#card-numbers).

## Response fields

A success response has HTTP status 200.

```json
{
  "mode": "live",
  "data": {
    "bin": "42467101",
    "scheme": "visa",
    "funding": "debit",
    "brand": "VISA",
    "category": "CLASSIC",
    "country": { "code": "PL", "name": "POLAND" },
    "issuer": { "name": "ING BANK SLASKI SA", "website": null, "phone": null },
    "currency": "PLN",
    "prepaid": false,
    "commercial": false
  }
}
```

`mode` is `live` or `test`. A test-mode organisation receives mock data. `mode` is then `test`.

| Field | Type | Meaning |
|-------|------|---------|
| `bin` | string | The BIN that matched the request. |
| `scheme` | string | `visa`, `mastercard`, `amex`, `discover`, `jcb`, `unionpay`, `diners`, or `unknown`. |
| `funding` | string | `credit`, `debit`, `prepaid`, or `unknown`. `credit` includes a charge card. |
| `brand` | string or null | The product name. Examples: `VISA`, `PLATINUM`. |
| `category` | string or null | The product level. Examples: `CLASSIC`, `GOLD`, `PLATINUM`. |
| `country.code` | string | The ISO 3166-1 alpha-2 code of the issuing country. |
| `country.name` | string | The name of the issuing country. |
| `issuer.name` | string or null | The name of the issuing bank. |
| `issuer.website` | string or null | The website of the issuing bank. |
| `issuer.phone` | string or null | The phone number of the issuing bank, in international format when known. |
| `currency` | string or null | The ISO 4217 code of the issuing country. This is not always the currency of the card account. |
| `prepaid` | boolean | `true` when the card is a prepaid card. |
| `commercial` | boolean | `true` when the card is a business card or a corporate card. |

`brand`, `category`, `currency`, and the issuer fields can be `null`. A null value means the data source has no value for that BIN.

The `data` object always contains every field in the table. If a field is absent, [contact support](/docs/support/contact/) and include the BIN and the request time.

More detail on currency, issuer contact data, and data sources is on the [data page](/docs/support/data/).

## The meta object

BLAPI-150KPM and BLAPI-500KPM add a `meta` object to a success response. A test-mode organisation also receives `meta`.

The `data` object is unchanged. `meta` is added next to it:

```json
"meta": { "longer_bin_available": true }
```

| Field | Type | Meaning |
|-------|------|---------|
| `meta.longer_bin_available` | boolean | `true` when the dataset has a longer record that starts with this BIN. |

On the free tier and on BLAPI-30KPM, the response does not contain `meta`. The API does not return `null` and does not return an error for this omission.

When the value is `true`, send the request again with more digits, up to 11. The second response can be more specific. Do not send more than 11 digits.

Example: you send `424671` and `longer_bin_available` is `true`. Send `42467101` next. The second response can use the longer record, and `longer_bin_available` can then be `false`.

## How the API matches a BIN

The API returns the longest record that matches the start of the BIN.

1. The API searches for the first 6 digits.
2. The API then searches for 7 digits, then 8 digits, and so on.
3. The search stops at the length that you sent.
4. The API returns the longest matching record.

Example: you send `42467101`. The API searches for `424671`, `4246710`, and `42467101`. If a record exists for `42467101`, the API returns that record. If not, it returns `4246710` or `424671`.

Send 8 or more digits when you can. Many ranges share the same first 6 digits.

## Errors

An error response has this shape:

```json
{
  "error": "QUOTA_EXCEEDED",
  "message": "Daily request quota exceeded",
  "upgrade_url": "https://app.binlookupapi.com/organisation/org_.../billing"
}
```

`upgrade_url` is not present on every error. When it is present, it opens the Billing page for your organisation.

| HTTP status | Error code | Cause |
|-------------|------------|-------|
| 400 | `BAD_REQUEST` | The body is not valid JSON, a field is missing, the number is out of range, or the body is larger than 1 KB. |
| 401 | `UNAUTHORIZED` | The API key is missing, not valid, revoked, or expired. |
| 403 | `FORBIDDEN` | The key does not have permission for this endpoint. |
| 403 | `FEATURE_NOT_AVAILABLE` | The plan does not include the feature. The message names the required plan. |
| 404 | `NOT_FOUND` | No record matches this BIN. |
| 429 | `QUOTA_EXCEEDED` | The organisation has used the daily quota. The quota resets at 00:00 UTC. On the free tier, the body includes `upgrade_url`. |
| 502 | `SERVICE_ERROR` | An internal error occurred. Send the request again later. |

On a [batch request](/docs/batch-lookups/), `NOT_FOUND` and `BAD_REQUEST` are per item. One item error does not stop the other items.

A 404 on every request is often a URL problem, not missing BIN data. Use `POST` and the path `/v1/bin` or `/v1/bins` on `https://api.binlookupapi.com`. A body with `"error": "NOT_FOUND"` means the URL is correct and the BIN is not in the data. See [Troubleshooting](/docs/support/troubleshooting/).

## Quota headers

Each success response and each 429 response includes these headers:

| Header | Meaning |
|--------|---------|
| `X-Quota-Limit` | The daily limit for the plan. |
| `X-Quota-Remaining` | The number of lookups that remain today. |
| `X-Quota-Reset` | The next reset time, as a Unix timestamp in seconds. |

```text
X-Quota-Limit: 10000
X-Quota-Remaining: 7482
X-Quota-Reset: 1706400000
```

There is no limit on requests per second. The daily quota is the only limit. Read `X-Quota-Remaining` and stop before it reaches zero.

When a single lookup returns 429, `X-Quota-Remaining` is `0`. A batch that is larger than the remaining quota returns 429, uses no quota, and `X-Quota-Remaining` shows the real remainder. See [Billing](/docs/subscriptions/#daily-quota).

## OpenAPI

1. Download [https://app.binlookupapi.com/openapi.json](https://app.binlookupapi.com/openapi.json).
2. Generate a client, or import the file into Postman or Insomnia.
3. Set the base URL to `https://api.binlookupapi.com`.
4. Set the bearer token to your API key.

`/openapi.yaml` on this website redirects to that JSON file.

## Stored results

BIN data receives small updates each week. You can store a response and reuse it. Refresh a stored result at least once each week. A stored result uses no daily quota.

## Related pages

- [Batch lookups](/docs/batch-lookups/)
- [Language guides](/docs/guides/)
- [Billing and quotas](/docs/subscriptions/)
- [API keys](/docs/api-keys/)
- [Data definitions](/docs/support/data/)
- [Troubleshooting](/docs/support/troubleshooting/)