BinSearchLookup API Documentation 2025 - Complete Developer Guide
Quick Summary
BinSearchLookup API is an enterprise-grade REST API for instant Bank Identification Number (BIN) and Issuer Identification Number (IIN) lookup. Get real-time card validation, issuer identification, brand detection (Visa, Mastercard, Amex, Discover), country data, and fraud prevention insights in under 100ms. Free tier available with 500 requests/month. Trusted by 5,000+ developers worldwide.
What's New
Six new endpoints and fields, live on every plan:
PrepaidandbrandLogofields, and a realsimilarBinslist, on every /lookup responseGET /lookup/search: filter the dataset by category, issuer, brand, type, or country, with aformat=csvexport optionPOST /validate: Luhn/format-validate a full card number, enriched with BIN data, never logs the full numberGET /issuers: browse distinct card issuers and how many BINs each one hasGET /stats/distribution: aggregate counts by brand, category, country, or type across the full dataset/webhooks/quota: get a signed POST when your account crosses 80/95/100% of its monthly quota
This comprehensive API documentation covers everything you need to integrate BinSearchLookup into your payment processing, e-commerce, or fintech application. Learn about API endpoints, authentication methods, request/response formats, error handling, rate limiting, and pricing tiers. Includes code examples in cURL, Python, JavaScript, PHP, Ruby, Java, Go, and C#.
Key Features
- ✓ Real-time BIN/IIN lookup - Instant card validation
- ✓ Card brand detection - Visa, MC, Amex, Discover
- ✓ Issuer identification - Bank and institution data
- ✓ Country & region data - ISO codes included
- ✓ Card type detection - Credit, debit, prepaid
- ✓ Fraud prevention support - Risk assessment data
- ✓ 99% uptime SLA - Enterprise reliability
- ✓ Response time <100ms - Lightning fast
- ✓ RESTful architecture - Standard HTTP/HTTPS
- ✓ Multi-language support - 8+ code examples
- ✓ PCI DSS compliant - Secure and certified
- ✓ 24/7 technical support - Always available
Official SDKs
Official clients for Node.js and Python, covering lookup, batch lookup, search, and card validation with built-in error handling.
npm install binsearchlookup
View on npm →
pip install binsearchlookup
View on PyPI →
Pricing Tiers - Choose Your Plan
60 req/min · 2 API keys
140 req/min · 5 API keys
200 req/min · 8 API keys
280 req/min · 15 API keys
Custom SLA
Single BIN Lookup - Real-Time Card Validation API Endpoint
Retrieve comprehensive, real-time information about any Bank Identification Number (BIN) or Issuer Identification Number (IIN). This primary API endpoint returns detailed issuer information, card brand (Visa, Mastercard, Amex, Discover), card type (credit, debit, prepaid), category, country of origin, bank name, and prepaid status. Perfect for payment processing, fraud prevention, and card validation in e-commerce applications. Response time: <100ms | 99% uptime | Supports 6-8 digit BINs.
To lookup a BIN, send a GET request to /lookup?bin={BIN_NUMBER} with headers
X-API-Key and
X-User-ID.
Example: /lookup?bin=551029 returns Mastercard debit card data in JSON format.
ENDPOINT DETAILS
/lookup?bin={bin}
bin
REQUIREDThe Bank Identification Number (6-8 digits) to lookup. Example: 551029
Must be passed as a query parameter in the URL.
REQUIRED HEADERS
X-API-Key
REQUIREDYour API key in the format: bsl_[64 character hash]
Generated from your account dashboard.
X-User-ID
REQUIREDYour User ID in UUID format. Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Found in Account Info under your settings.
RESPONSE FIELDS
| Field | Type | Description |
|---|---|---|
bin |
String | The BIN that was looked up |
success |
Boolean | Whether the lookup was successful |
data |
Object | Detailed BIN information (see below) |
statusCode |
Number | HTTP status code of the response |
responseTime |
Number | Time taken to process the request in milliseconds |
LIMITS OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
requestsPerMinute |
Number | Maximum requests allowed per minute |
requestsPerMonth |
Number | Maximum requests allowed per month |
maxApiKeys |
Number | Maximum API keys allowed for your account |
RESET TIMES OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
minuteWindow |
String | ISO timestamp when the minute counter resets |
monthWindow |
String | ISO timestamp when the month counter resets |
Alert Management
Configure and manage alerts for your API usage. Get notified when you approach your usage limits.
GET ALERTS ENDPOINT
/api/alerts
limit
OPTIONALLimit the number of alerts returned. Default: 10, Maximum: 50.
Pass as a query parameter: /api/alerts?limit=20
SET ALERT ENDPOINT
/api/alerts
alert_type
REQUIREDThe type of alert to set. Possible values: minute, hour, day, month.
threshold
REQUIREDThe usage threshold at which to trigger the alert.
Must be a positive integer.
enabled
OPTIONALWhether the alert is enabled. Default: true.
Set to false to disable the alert without deleting it.
GET NOTIFICATIONS ENDPOINT
/api/alerts/notifications
limit
OPTIONALLimit the number of notifications returned. Default: 10, Maximum: 50.
Pass as a query parameter: /api/alerts/notifications?limit=20
REQUIRED HEADERS
X-API-Key
REQUIREDYour API key in the format: bsl_[64 character hash]
Generated from your account dashboard.
X-User-ID
REQUIREDYour User ID in UUID format. Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Found in Account Info under your settings.
ALERT OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
id |
Number | Unique identifier for the alert |
user_id |
Number | Your user ID |
alert_type |
String | Type of alert (minute, hour, day, month) |
threshold |
Number | The usage threshold that triggers the alert |
enabled |
Boolean | Whether the alert is currently active |
NOTIFICATION OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
id |
Number | Unique identifier for the notification |
user_id |
Number | Your user ID |
alert_type |
String | Type of alert that was triggered |
threshold |
Number | The threshold that was exceeded |
current_usage |
Number | The usage value that triggered the alert |
triggered_at |
String | ISO timestamp when the alert was triggered |
Health Check
Verify the status of the API service and database connectivity. Use these endpoints to monitor API availability.
SERVICE HEALTH ENDPOINT
/health
Check the overall status of the API service. No authentication required.
DATABASE HEALTH ENDPOINT
/health/db
X-Admin-Key
REQUIRED IN PRODUCTIONAdmin key required for database health checks in production environment.
Not required in development mode.
RESPONSE FIELDS
| Field | Type | Description |
|---|---|---|
status |
String | Service status (OK or ERROR) |
timestamp |
String | ISO timestamp of the health check |
database |
String | Database connection status (Connected or Disconnected) - /health/db only |
Authentication & API Keys
Learn how to authenticate your API requests using API keys and user IDs.
API KEY FORMAT
API keys must be in the format: bsl_[64 character hash]
Example: bsl_4eC39HqLyjWDarjtT1zdp7dc1234567890abcdef1234567890abcdef12
API keys are generated in your account dashboard and should be kept secure.
USER ID FORMAT
User IDs must be in UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Your User ID can be found in Account Info under your settings.
KEY ROTATION
For security best practices, rotate your API keys regularly.
You can generate new keys and delete old ones from your account dashboard.
Each account tier has a maximum number of active API keys allowed:
- Free: 2 API keys
- Starter: 5 API keys
- Pro: 15 API keys
- Enterprise: 190 API keys
Required Headers
All API requests require specific headers for authentication and proper processing.
STANDARD HEADERS
| Header | Required | Description | Example |
|---|---|---|---|
X-API-Key |
Yes | Your API authentication key | bsl_4eC39HqLyjWDarjtT1zdp7dc... |
X-User-ID |
Yes | Your user identifier | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
Content-Type |
For POST | Must be application/json for requests with body | application/json |
OPTIONAL HEADERS
| Header | Required | Description | Example |
|---|---|---|---|
User-Agent |
No | Identify your application | MyApp/1.0.0 |
X-Request-ID |
No | Unique ID for request tracing | req_1234567890 |
Error Codes
Reference for all API error codes and their meanings.
COMMON ERROR CODES
| HTTP Status | Error Code | Description | Solution |
|---|---|---|---|
| 400 | MISSING_BIN_PARAMETER |
BIN parameter is required but missing | Include bin parameter in query string |
| 400 | INVALID_BIN |
BIN format is invalid | Use 6-8 digit BIN numbers |
| 401 | MISSING_API_KEY |
X-API-Key header is missing | Include X-API-Key header |
| 401 | MISSING_USER_ID |
X-User-ID header is missing | Include X-User-ID header |
| 401 | INVALID_API_KEY_FORMAT |
API key format is invalid | Use bsl_[64 characters] format |
| 401 | INVALID_USER_ID_FORMAT |
User ID format is invalid | Use UUID format |
| 401 | UNAUTHORIZED |
API key or user ID is invalid | Check your credentials |
| 403 | ACCESS_DENIED |
User doesn't have access to requested resource | Check user permissions |
| 403 | NO_SUBSCRIPTION |
No active subscription found | Subscribe to a plan |
| 403 | SUBSCRIPTION_INACTIVE |
Subscription is not active | Renew your subscription |
| 403 | SUBSCRIPTION_EXPIRED |
Subscription has expired | Renew your subscription |
| 429 | RATE_LIMIT_EXCEEDED |
Too many requests | Wait before making more requests |
| 500 | INTERNAL_ERROR |
Internal server error | Contact support if persistent |
DATA OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
BIN |
String | The BIN number |
Brand |
String | Card brand (e.g., VISA, MASTERCARD) |
Type |
String | Card type (e.g., DEBIT, CREDIT) |
Category |
String | Card category (e.g., STANDARD, PREMIUM) |
Issuer |
String | Name of the issuing bank |
IssuerPhone |
String | Phone number of the issuer |
IssuerUrl |
String | Website of the issuer |
isoCode2 |
String | 2-letter country code |
isoCode3 |
String | 3-letter country code |
CountryName |
String | Full country name |
similarBins |
Array | Array of similar BINs |
cached |
Boolean | Whether the result was served from cache |
Quota Information
Check your current API usage and limits. Monitor your remaining requests for the current minute and month.
ENDPOINT DETAILS
/api/quota/{publicUserId}
publicUserId
REQUIREDYour public user ID in UUID format. Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Found in Account Info under your settings.
REQUIRED HEADERS
X-API-Key
REQUIREDYour API key in the format: bsl_[64 character hash]
Generated from your account dashboard.
RESPONSE FIELDS
| Field | Type | Description |
|---|---|---|
accountType |
String | Your current account type (free, starter, pro, enterprise) |
usage |
Object | Current usage statistics (see below) |
limits |
Object | Your account limits (see below) |
resetTimes |
Object | When usage counters reset (see below) |
USAGE OBJECT FIELDS
| Field | Type | Description | |
|---|---|---|---|
requestsThisMinute |
Number | Number of requests made in the current minute | |
requestsThisMonth |
Number | Number of requests made in the current month |
| Field | Type | Description |
|---|---|---|
summary |
Object | Summary of the batch operation (see below) |
results |
Array | Array of BIN lookup results (same format as single lookup) |
quota |
Object | Current quota usage after processing the batch |
SUMMARY OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
totalRequested |
Number | Total number of BINs in the request |
successful |
Number | Number of successfully processed BINs |
failed |
Number | Number of BINs that failed processing |
totalResponseTime |
Number | Total time taken to process the batch in milliseconds |
QUOTA OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
accountType |
String | Your current account type |
usage |
Object | Current usage statistics |
limits |
Object | Your account limits |
resetTimes |
Object | When usage counters reset |
Search / Filter BINs
Filter the BIN dataset by category, issuer, brand, type, and/or country. At least one filter is required. Costs exactly one credit per call, regardless of how many rows match.
ENDPOINT DETAILS
/lookup/search
category, issuer, brand, type, country
AT LEAST ONE REQUIREDMultiple filters are AND'd together. Example: ?issuer=LEWIS+%26+CLARK+BANK
limit
OPTIONALMax rows to return, capped at your plan's requests-per-minute. Omit or pass unlimited for your plan's full cap.
format
OPTIONALPass csv to receive the results as a CSV download instead of JSON. Same one-credit cost.
RESPONSE FIELDS
| Field | Type | Description |
|---|---|---|
count | Number | Rows returned in this response |
truncated | Boolean | True if the scan budget was hit before the full dataset was searched |
results | Array | Matching BIN records (same shape as a single lookup) |
Validate Card Number
Runs a Luhn checksum and length check (12-19 digits) against a full card number, and enriches the response with the same BIN data /lookup returns. The full card number is never logged or persisted. Only its first-8-digit BIN prefix goes to your request history. One credit per call.
ENDPOINT DETAILS
/validate
cardNumber
REQUIREDFull card number, digits only or with separators (spaces/dashes stripped automatically). Example: {"cardNumber": "4111111111111111"}
RESPONSE FIELDS
| Field | Type | Description |
|---|---|---|
cardNumberMasked | String | First 6 and last 4 digits only, e.g. 411111******1111 |
lengthValid | Boolean | 12-19 digits |
luhnValid | Boolean | Passes the Luhn checksum |
data | Object | BIN data for the card, same shape as a single lookup |
Issuer Directory
Distinct card issuer names and how many BINs each one has, optionally filtered by country. Same one-credit-per-call model as search.
ENDPOINT DETAILS
/issuers
country
OPTIONALFull country name to filter by, e.g. UNITED STATES.
limit
OPTIONALMax rows to return, capped at your plan's requests-per-minute.
Distribution Stats
Counts per distinct value for one field across the entire dataset, e.g. how many BINs are VISA vs MASTERCARD, or CREDIT vs DEBIT. One credit per call.
ENDPOINT DETAILS
/stats/distribution
groupBy
REQUIREDOne of brand, category, country, type.
Quota Webhooks
Register a URL to be POSTed to when your account crosses 80%, 95%, or 100% of its monthly request quota. Config management only. These endpoints never consume a credit.
ENDPOINTS
/webhooks/quota
url
REQUIREDHTTPS (or HTTP) endpoint to receive notifications. Setting a new URL replaces any existing one.
Also GET /webhooks/quota (current config, never returns the secret) and DELETE /webhooks/quota (remove it).
VERIFYING DELIVERIES
The secret is returned once, at creation time. Every delivery includes an X-BSL-Signature header: HMAC-SHA256 of the raw request body, using that secret as the key.
Quota Information
Check your current API usage and limits. Monitor your remaining requests for the current minute and month.
ENDPOINT DETAILS
/api/quota/{publicUserId}
publicUserId
REQUIREDYour public user ID in UUID format. Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Found in Account Info under your settings.
REQUIRED HEADERS
X-API-Key
REQUIREDYour API key in the format: bsl_[64 character hash]
Generated from your account dashboard.
RESPONSE FIELDS
| Field | Type | Description |
|---|---|---|
accountType |
String | Your current account type (free, starter, pro, enterprise) |
usage |
Object | Current usage statistics (see below) |
limits |
Object | Your account limits (see below) |
resetTimes |
Object | When usage counters reset (see below) |
USAGE OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
requestsThisMinute |
Number | Number of requests made in the current minute |
requestsThisMonth |
Number | Number of requests made in the current month |
LIMITS OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
requestsPerMinute |
Number | Maximum requests allowed per minute |
requestsPerMonth |
Number | Maximum requests allowed per month |
maxApiKeys |
Number | Maximum API keys allowed for your account |
RESET TIMES OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
minuteWindow |
String | ISO timestamp when the minute counter resets |
monthWindow |
String | ISO timestamp when the month counter resets |
Alert Management
Configure and manage alerts for your API usage. Get notified when you approach your usage limits.
GET ALERTS ENDPOINT
/api/alerts
limit
OPTIONALLimit the number of alerts returned. Default: 10, Maximum: 50.
Pass as a query parameter: /api/alerts?limit=20
SET ALERT ENDPOINT
/api/alerts
alert_type
REQUIREDThe type of alert to set. Possible values: minute, hour, day, month.
threshold
REQUIREDThe usage threshold at which to trigger the alert.
Must be a positive integer.
enabled
OPTIONALWhether the alert is enabled. Default: true.
Set to false to disable the alert without deleting it.
GET NOTIFICATIONS ENDPOINT
/api/alerts/notifications
limit
OPTIONALLimit the number of notifications returned. Default: 10, Maximum: 50.
Pass as a query parameter: /api/alerts/notifications?limit=20
REQUIRED HEADERS
X-API-Key
REQUIREDYour API key in the format: bsl_[64 character hash]
Generated from your account dashboard.
X-User-ID
REQUIREDYour User ID in UUID format. Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Found in Account Info under your settings.
ALERT OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
id |
Number | Unique identifier for the alert |
user_id |
Number | Your user ID |
alert_type |
String | Type of alert (minute, hour, day, month) |
threshold |
Number | The usage threshold that triggers the alert |
enabled |
Boolean | Whether the alert is currently active |
NOTIFICATION OBJECT FIELDS
| Field | Type | Description |
|---|---|---|
id |
Number | Unique identifier for the notification |
user_id |
Number | Your user ID |
alert_type |
String | Type of alert that was triggered |
threshold |
Number | The threshold that was exceeded |
current_usage |
Number | The usage value that triggered the alert |
triggered_at |
String | ISO timestamp when the alert was triggered |
Health Check
Verify the status of the API service and database connectivity. Use these endpoints to monitor API availability.
SERVICE HEALTH ENDPOINT
/health
Check the overall status of the API service. No authentication required.
DATABASE HEALTH ENDPOINT
/health/db
X-Admin-Key
REQUIRED IN PRODUCTIONAdmin key required for database health checks in production environment.
Not required in development mode.
RESPONSE FIELDS
| Field | Type | Description |
|---|---|---|
status |
String | Service status (OK or ERROR) |
timestamp |
String | ISO timestamp of the health check |
database |
String | Database connection status (Connected or Disconnected) - /health/db only |
Authentication & API Keys
Learn how to authenticate your API requests using API keys and user IDs.
API KEY FORMAT
API keys must be in the format: bsl_[64 character hash]
Example: bsl_4eC39HqLyjWDarjtT1zdp7dc1234567890abcdef1234567890abcdef12
API keys are generated in your account dashboard and should be kept secure.
USER ID FORMAT
User IDs must be in UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Your User ID can be found in Account Info under your settings.
KEY ROTATION
For security best practices, rotate your API keys regularly.
You can generate new keys and delete old ones from your account dashboard.
Each account tier has a maximum number of active API keys allowed:
- Free: 2 API keys
- Starter: 5 API keys
- Pro: 15 API keys
- Enterprise: 190 API keys
Required Headers
All API requests require specific headers for authentication and proper processing.
STANDARD HEADERS
| Header | Required | Description | Example |
|---|---|---|---|
X-API-Key |
Yes | Your API authentication key | bsl_4eC39HqLyjWDarjtT1zdp7dc... |
X-User-ID |
Yes | Your user identifier | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
Content-Type |
For POST | Must be application/json for requests with body | application/json |
OPTIONAL HEADERS
| Header | Required | Description | Example |
|---|---|---|---|
User-Agent |
No | Identify your application | MyApp/1.0.0 |
X-Request-ID |
No | Unique ID for request tracing | req_1234567890 |
Error Codes
Reference for all API error codes and their meanings.
COMMON ERROR CODES
| HTTP Status | Error Code | Description | Solution |
|---|---|---|---|
| 400 | MISSING_BIN_PARAMETER |
BIN parameter is required but missing | Include bin parameter in query string |
| 400 | INVALID_BIN |
BIN format is invalid | Use 6-8 digit BIN numbers |
| 401 | MISSING_API_KEY |
X-API-Key header is missing | Include X-API-Key header |
| 401 | MISSING_USER_ID |
X-User-ID header is missing | Include X-User-ID header |
| 401 | INVALID_API_KEY_FORMAT |
API key format is invalid | Use bsl_[64 characters] format |
| 401 | INVALID_USER_ID_FORMAT |
User ID format is invalid | Use UUID format |
| 401 | UNAUTHORIZED |
API key or user ID is invalid | Check your credentials |
| 403 | ACCESS_DENIED |
User doesn't have access to requested resource | Check user permissions |
| 403 | NO_SUBSCRIPTION |
No active subscription found | Subscribe to a plan |
| 403 | SUBSCRIPTION_INACTIVE |
Subscription is not active | Renew your subscription |
| 403 | SUBSCRIPTION_EXPIRED |
Subscription has expired | Renew your subscription |
| 429 | RATE_LIMIT_EXCEEDED |
Too many requests | Wait before making more requests |
| 500 | INTERNAL_ERROR |
Internal server error | Contact support if persistent |
Free Tier
Our free tier provides basic access to the BIN lookup API with reasonable limits for testing and development.
FEATURES & LIMITS
| Feature | Limit |
|---|---|
| Requests Per Minute | 20 |
| Requests Per Month | 1,000 |
| API Keys | 1 |
| Batch Size | 50 BINs per request |
| Data Encryption | ✓ Included |
| SSO | ✓ Included |
| Price | Free |
Starter Tier
Our starter tier is perfect for small businesses and applications with moderate BIN lookup needs.
FEATURES & LIMITS
| Feature | Limit |
|---|---|
| Requests Per Minute | 60 |
| Requests Per Month | 10,000 |
| API Keys | 3 |
| Batch Size | 50 BINs per request |
| Data Encryption | ✓ Included |
| SSO | ✓ Included |
| Price | $25/month |
Pro Tier
Our pro tier is designed for businesses with high-volume BIN lookup requirements.
FEATURES & LIMITS
| Feature | Limit |
|---|---|
| Requests Per Minute | 280 |
| Requests Per Month | 250,000 |
| API Keys | 15 |
| Batch Size | 50 BINs per request |
| Data Encryption | ✓ Included |
| SSO | ✓ Included |
| Price | $175/month |
Enterprise Tier
Our enterprise tier offers unlimited requests for high-volume applications with dedicated support.
FEATURES & LIMITS
| Feature | Limit |
|---|---|
| Requests Per Minute | 768 |
| Requests Per Month | Unlimited |
| API Keys | 190 |
| Batch Size | 50 BINs per request |
| Data Encryption | ✓ Included |
| SSO | ✓ Included |
| Price | $980/month |