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.

The machine-readable specification is the OpenAPI file. 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.

Authentication

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

Authorization: Bearer YOUR_API_KEY

Create the key on the API Keys page. See API keys.

Look up one BIN

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

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

{ "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.

Response fields

A success response has HTTP status 200.

{
  "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.

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 and include the BIN and the request time.

More detail on currency, issuer contact data, and data sources is on the data page.

The meta object

BLAPI-150KPM, BLAPI-500KPM and BLAPI-1MPM 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:

"meta": { "longer_bin_available": true }

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:

{
  "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.

On a batch request, 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.

Quota headers

Each success response and each 429 response includes these headers:

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

On BLAPI-1MPM, X-Quota-Limit is the included lookups for the billing period (1000000), X-Quota-Remaining is the included lookups left in the period, and X-Quota-Reset is the end of the period. See BLAPI-1MPM quota headers.

There is no fixed limit on requests per second. On the free tier and BLAPI-30KPM to BLAPI-500KPM, the daily quota is the plan limit; technical capacity and acceptable-use limits apply to every plan. See Rate limits. Read X-Quota-Remaining and stop before it reaches zero.

When a single lookup returns 429, X-Quota-Remaining is 0, and so is X-Credits-Remaining on BLAPI-1MPM. A batch that is larger than the remaining quota returns 429, uses no quota, and X-Quota-Remaining shows the real remainder. See Billing.

OpenAPI

1. Download 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
• Language guides
• Billing and quotas
• API keys
• Data definitions
• Troubleshooting