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 4 to 8 digits of a payment card number.

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

Endpoint: POST /v1/bin

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 4 and 8 digits (range: 1000 to 99999999). 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)

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

Field	Type	Description
`bin`	`string`	The BIN that was looked up
`scheme`	`string`	Card network: `visa`, `mastercard`, `amex`, `discover`, `jcb`, `unionpay`, `diners`, or `unknown`
`funding`	`string`	Funding type: `credit`, `debit`, `prepaid`, or `unknown`
`brand`	`string \| null`	Card brand or product name (e.g. `"VISA"`, `"PLATINUM"`)
`category`	`string \| null`	Card category (e.g. `"CLASSIC"`, `"GOLD"`, `"PLATINUM"`)
`country.code`	`string`	ISO 3166-1 alpha-2 country code
`country.name`	`string`	Country name
`issuer.name`	`string \| null`	Issuing bank name
`issuer.website`	`string \| null`	Issuing bank website
`issuer.phone`	`string \| null`	Issuing bank phone number
`currency`	`string \| null`	ISO 4217 currency code
`prepaid`	`boolean`	Whether the card is prepaid
`commercial`	`boolean`	Whether the card is a commercial/business card

Test Mode

Test mode organisations receive mock BIN data. The following test BINs return specific responses:

BIN	Scheme	Funding	Country	Notes
`45839201`	Visa	Credit	Japan	Minimal issuer data
`52741836`	Mastercard	Credit	Mauritius	Full issuer data
`41928374`	Visa	Credit	Azerbaijan	Commercial card
`55012847`	Mastercard	Prepaid	Cameroon	Prepaid card

All other BINs return the default mock response (Polish Visa debit card).

Test mode has a daily limit of 500 requests. Quota headers are included in all responses.

Errors

All error responses follow this format:

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

Error Codes

Status	Error Code	Description
`400`	`BAD_REQUEST`	Invalid or missing request body. The `number` field must be an integer between 4 and 8 digits.
`401`	`UNAUTHORIZED`	Missing, invalid, revoked, or expired API key.
`402`	`PAYMENT_REQUIRED`	No active subscription. Subscribe to a plan in the dashboard under Billing.
`403`	`FORBIDDEN`	API key lacks required permissions. Contact support if you believe this is an error.
`404`	`NOT_FOUND`	The requested BIN was not found.
`429`	`QUOTA_EXCEEDED`	Daily request quota exceeded. Quota resets at midnight UTC. See Subscriptions.
`502`	`SERVICE_ERROR`	An internal error occurred. Try again later.

Quota Headers

Every successful response includes quota headers:

Header	Description
`X-Quota-Limit`	Total daily request allowance for the plan
`X-Quota-Remaining`	Requests remaining for the current day
`X-Quota-Reset`	Unix timestamp (seconds) when the quota resets

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

Use 8 digits when available for better accuracy
The API supports 4-8 digit lookups
Longer BINs provide more precise results

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