API Reference

Complete documentation for the BIN Lookup API endpoint.

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

Endpoint: POST /v1/bin

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.

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

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.

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