BIN Lookup API Reference

Complete documentation for the BIN Lookup API endpoints.

Overview

The BIN Lookup API provides card metadata from a Bank Identification Number (BIN) - the first 6 – 11 digits of a payment card number.

Base URL: https://api.binlookupapi.com

The full machine-readable specification is available as OpenAPI (JSON) — generated from the API itself, so it’s always up to date. Import it into Postman, Insomnia, or a code generator.

Or fork the ready-made collection directly into your Postman workspace:

Authentication

All requests must include an API key in the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

API keys are created in the dashboard under API Keys. The full key is shown only once at creation — store it securely. You can revoke keys at any time from the same page.

Making a Request

Send a POST request with a JSON body containing the BIN as an integer.

Request

POST /v1/bin
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "number": 42467101
}

The number field must be an integer between 6 and 11 digits (range: 100000 to 99999999999). Digit-only strings (e.g. "42467101") are accepted for compatibility and coerced to the same integer value — leading zeroes are not preserved. Do not pass the full card number.

cURL Example

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

Response

Success (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
  }
}

Every successful response includes quota headers — see Subscriptions for details.

Response Fields

The top-level mode field is "live" or "test" — test-mode organisations receive mock data so you can integrate before going live.

The meta Object

On plans that include the meta feature (BLAPI-150KPM and above), successful responses also carry a meta object:

{
  "mode": "live",
  "data": { "...": "..." },
  "meta": {
    "longer_bin_available": true
  }
}

On plans without the feature the meta field is omitted entirely — no null, no error. Test-mode organisations get every plan feature, and longer_bin_available behaves deterministically against the mock data so you can exercise both branches during integration.

Batch Lookups

On the BLAPI-500KPM plan (and in test mode), POST /v1/bins looks up 1 to 2,000 BINs in one request and returns one result per submitted number, in the same order. Each entry follows the same validation rules as a single lookup, gets its own per-item data, meta, or error, and counts as one lookup against the daily quota.

curl -X POST "https://api.binlookupapi.com/v1/bins" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": [400062, "400597", 99999999]}'

See Batch Lookups for full documentation — per-item errors, card number redaction, and quota accounting.

Free Tier

Organisations without an active subscription get 10 requests per day for free, with real production data — so you can try the API before subscribing. Once the free allowance is used up, requests return 429 QUOTA_EXCEEDED with an upgrade_url pointing to your organisation’s billing page.

Quota headers are included in all responses. See Subscriptions for details.

Errors

All error responses follow this format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}

Error Codes

On batch requests, NOT_FOUND and BAD_REQUEST are returned per item inside the results array — a failed entry doesn’t affect the rest of the batch. A batch larger than the remaining daily quota returns 429 and consumes nothing.

Quota Headers

Every successful response includes quota headers:

These same headers are returned on 429 responses when the quota is exceeded, with X-Quota-Remaining set to 0. The exception is a batch request larger than the remaining quota: it consumes nothing, and X-Quota-Remaining reports the actual remaining quota so you can split the batch and retry.

Example headers:

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

Best Practices

BIN Length

• The API supports 6-11 digit lookups
• Use the longest prefix you have (up to 11 digits) for the most precise match
• On plans with the meta feature, check meta.longer_bin_available — when true, resubmitting with more digits may return more specific data

Caching

• BIN data changes infrequently — cache results for 24-48 hours
• Implement cache invalidation based on your needs
• Reduces API costs and improves performance

Error Handling

• Check the HTTP status code for errors
• Implement retry logic for 5xx errors
• Handle rate limits gracefully with exponential backoff