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 1,000 requests/month. Trusted by 5,000+ developers worldwide.
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
Pricing Tiers - Choose Your Plan
10 req/min
50 req/min
200 req/min
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: 1 API key
- Starter: 3 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 |
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: 1 API key
- Starter: 3 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 | 78,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 |