BinSearchLookup API Documentation
Complete API documentation for BinSearchLookup - A comprehensive Bank Identification Number (BIN) lookup service. This documentation covers all endpoints, authentication methods, request/response formats, error handling, and account tiers.
Single BIN Lookup
Retrieve detailed information about a Bank Identification Number (BIN) or Issuer Identification Number (IIN). Returns issuer information, brand, type, category, country, and whether the card is prepaid.
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 |