# BinSearchLookup API - LLM Manifest

## Company Information

**Company Name:** BinSearchLookup  
**Website:** https://www.binsearchlookup.com  
**API Base URL:** https://api.binsearchlookup.com  
**Support Email:** contact@binsearchlookup.com  
**API Status:** https://stats.uptimerobot.com/fEv8yBZBFb

## Service Overview

BinSearchLookup is a Bank Identification Number (BIN) / Issuer Identification Number (IIN) lookup API service that provides detailed information about payment cards including issuer details, card brand, type, category, country, and prepaid status. The service maintains a database of over 100,000 BINs with real-time validation and quality control to ensure high accuracy.

### Key Features
- **Real-time BIN validation** with quality control checks before each response
- **Single and batch lookup** endpoints (up to 50 BINs per request)
- **High accuracy** with industry-leading data quality
- **Instant API access** - no DNS propagation or latency delays after key creation
- **Comprehensive data** including issuer phone numbers, URLs, and similar BIN suggestions
- **Smart caching** for improved performance
- **Usage monitoring** with quota tracking and alert management
- **Webhook support** for event notifications

### Database Characteristics
- **Coverage:** Over 100,000 BINs
- **Updates:** Dynamic - database is validated and updated as needed
- **Quality Control:** Automated checks for missing or inconsistent data
- **Accuracy:** Industry-leading accuracy rates (exact percentage not disclosed)

## Authentication

### Getting Started
1. Visit https://www.binsearchlookup.com/login
2. Navigate to your dashboard
3. Click on "API Keys" in the menu
4. Click "Create API Key"
5. Enter a name for your API key
6. Receive your API Key and User ID immediately
7. Start making requests - **no waiting period or DNS propagation**

### Finding Your User ID
Your User ID can be found in two locations:
1. **When creating an API key** - displayed alongside the new key
2. **Settings menu** - Navigate to Settings → Account Settings → Account ID

### Authentication Headers

All API requests require the following headers:

```
X-API-Key: bsl_[64 character hash]
X-User-ID: [UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]
```

**API Key Format:** `bsl_` followed by 64 alphanumeric characters  
**User ID Format:** Standard UUID (32 hexadecimal digits with hyphens)

### Security Best Practices
- Rotate API keys regularly from your dashboard
- Never expose API keys in client-side code
- Use environment variables to store credentials
- Monitor API key usage through the dashboard
- Delete unused API keys immediately

## Security & Compliance

### Data Protection
- **Email and password encryption** for user accounts
- **Secure API key generation** with cryptographic hashing
- **Data encryption in transit** via HTTPS/TLS
- **Payment processing** handled by Stripe (PCI-DSS Level 1 certified)

### Compliance Standards
- **GDPR** (General Data Protection Regulation) - European Union
- **CCPA** (California Consumer Privacy Act) - United States
- **PIPEDA** (Personal Information Protection and Electronic Documents Act) - Canada
- **LGPD** (Lei Geral de Proteção de Dados) - Brazil
- **Quebec Bill 25** (Law 25) - Quebec, Canada

### Note on Certifications
BinSearchLookup is compliant with major data protection regulations. Payment processing is handled by Stripe, which maintains PCI-DSS Level 1 certification. The service is not independently SOC2 certified.

## API Endpoints

### 1. Single BIN Lookup

**Endpoint:** `GET /lookup?bin={bin}`

Retrieve detailed information about a single Bank Identification Number.

**Parameters:**
- `bin` (required): 6-8 digit BIN/IIN number

**Example Request:**
```bash
curl -X GET \
  "https://api.binsearchlookup.com/lookup?bin=551029" \
  -H "X-API-Key: bsl_your_api_key_here" \
  -H "X-User-ID: your-user-id-here"
```

**Example Response:**
```json
{
  "bin": "551029",
  "success": true,
  "data": {
    "BIN": "551029",
    "Brand": "MASTERCARD",
    "Type": "DEBIT",
    "Category": "STANDARD",
    "Issuer": "BANK OF MONTREAL",
    "IssuerPhone": "+18772255266",
    "IssuerUrl": "http://www.bmo.com",
    "isoCode2": "CA",
    "isoCode3": "CAN",
    "CountryName": "CANADA",
    "similarBins": [],
    "cached": false,
    "responseTime": 2
  },
  "statusCode": 200,
  "responseTime": 17
}
```

**Response Fields:**
- `bin`: The queried BIN
- `success`: Boolean indicating lookup success
- `data.BIN`: The BIN number
- `data.Brand`: Card brand (VISA, MASTERCARD, AMEX, etc.)
- `data.Type`: Card type (DEBIT, CREDIT)
- `data.Category`: Card category (STANDARD, PREMIUM, PLATINUM, etc.)
- `data.Issuer`: Name of issuing bank
- `data.IssuerPhone`: Bank contact phone number
- `data.IssuerUrl`: Bank website URL
- `data.isoCode2`: 2-letter country code (ISO 3166-1 alpha-2)
- `data.isoCode3`: 3-letter country code (ISO 3166-1 alpha-3)
- `data.CountryName`: Full country name
- `data.similarBins`: Array of related BINs
- `data.cached`: Whether result was served from cache
- `data.responseTime`: Internal processing time (ms)
- `statusCode`: HTTP status code
- `responseTime`: Total response time (ms)

---

### 2. Batch BIN Lookup

**Endpoint:** `POST /lookup/batch`

Process multiple BIN lookups in a single request with summary statistics.

**Request Body:**
```json
{
  "bins": ["551029", "411111", "371449"]
}
```

**Limits:**
- Maximum 50 BINs per request (all tiers)
- Each BIN counts toward your monthly quota

**Headers Required:**
- `X-API-Key`: Your API key
- `X-User-ID`: Your user ID
- `Content-Type`: application/json

**Example Request:**
```bash
curl -X POST \
  "https://api.binsearchlookup.com/lookup/batch" \
  -H "X-API-Key: bsl_your_api_key_here" \
  -H "X-User-ID: your-user-id-here" \
  -H "Content-Type: application/json" \
  -d '{"bins": ["551029", "411111", "371449"]}'
```

**Example Response:**
```json
{
  "summary": {
    "totalRequested": 3,
    "successful": 3,
    "failed": 0,
    "totalResponseTime": 45
  },
  "results": [
    {
      "bin": "551029",
      "success": true,
      "data": { /* Same format as single lookup */ }
    }
  ],
  "quota": {
    "accountType": "pro",
    "usage": {
      "requestsThisMinute": 5,
      "requestsThisMonth": 1245
    },
    "limits": {
      "requestsPerMinute": 280,
      "requestsPerMonth": 78000,
      "maxApiKeys": 15
    }
  }
}
```

---

### 3. Quota Information

**Endpoint:** `GET /api/quota/{publicUserId}`

Check current API usage and remaining quota.

**Parameters:**
- `publicUserId` (path parameter): Your public user ID (UUID format)

**Example Request:**
```bash
curl -X GET \
  "https://api.binsearchlookup.com/api/quota/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: bsl_your_api_key_here"
```

**Example Response:**
```json
{
  "accountType": "pro",
  "usage": {
    "requestsThisMinute": 5,
    "requestsThisMonth": 1245
  },
  "limits": {
    "requestsPerMinute": 280,
    "requestsPerMonth": 78000,
    "maxApiKeys": 15
  },
  "resetTimes": {
    "minuteWindow": "2025-10-14T12:34:00Z",
    "monthWindow": "2025-11-01T00:00:00Z"
  }
}
```

---

### 4. Alert Management

#### Get Alerts
**Endpoint:** `GET /api/alerts?limit={limit}`

Retrieve configured usage alerts.

**Query Parameters:**
- `limit` (optional): Number of alerts to return (default: 10, max: 50)

**Example Request:**
```bash
curl -X GET \
  "https://api.binsearchlookup.com/api/alerts?limit=20" \
  -H "X-API-Key: bsl_your_api_key_here" \
  -H "X-User-ID: your-user-id-here"
```

#### Create Alert
**Endpoint:** `POST /api/alerts`

Configure usage threshold alerts.

**Request Body:**
```json
{
  "alert_type": "month",
  "threshold": 50000,
  "enabled": true
}
```

**Alert Types:**
- `minute`: Per-minute request threshold
- `hour`: Per-hour request threshold
- `day`: Per-day request threshold
- `month`: Per-month request threshold

**Example Request:**
```bash
curl -X POST \
  "https://api.binsearchlookup.com/api/alerts" \
  -H "X-API-Key: bsl_your_api_key_here" \
  -H "X-User-ID: your-user-id-here" \
  -H "Content-Type: application/json" \
  -d '{"alert_type": "month", "threshold": 50000, "enabled": true}'
```

#### Get Notifications
**Endpoint:** `GET /api/alerts/notifications?limit={limit}`

Retrieve triggered alert notifications.

**Query Parameters:**
- `limit` (optional): Number of notifications to return (default: 10, max: 50)

**Example Response:**
```json
[
  {
    "id": 123,
    "user_id": 456,
    "alert_type": "month",
    "threshold": 50000,
    "current_usage": 51234,
    "triggered_at": "2025-10-14T10:30:00Z"
  }
]
```

---

### 5. Health Check

#### Service Health
**Endpoint:** `GET /health`

Check API service status (no authentication required).

**Example Request:**
```bash
curl -X GET "https://api.binsearchlookup.com/health"
```

**Example Response:**
```json
{
  "status": "OK",
  "timestamp": "2025-10-14T12:00:00Z"
}
```

#### Database Health
**Endpoint:** `GET /health/db`

Check database connectivity status.

**Authentication:**
- Development: No authentication required
- Production: Requires `X-Admin-Key` header

**Example Response:**
```json
{
  "status": "OK",
  "database": "Connected",
  "timestamp": "2025-10-14T12:00:00Z"
}
```

---

## Account Tiers & Pricing

### Free Tier
**Price:** $0/month

**Limits:**
- 20 requests per minute
- 1,000 requests per month
- 1 API key
- 50 BINs per batch request

**Features:**
- ✅ Data encryption
- ✅ Single Sign-On (SSO)
- ✅ Basic support via email
- ✅ Access to all endpoints

**Best For:** Testing, development, and low-volume applications

---

### Starter Tier
**Price:** $25/month

**Limits:**
- 60 requests per minute
- 10,000 requests per month
- 3 API keys
- 50 BINs per batch request

**Features:**
- ✅ Data encryption
- ✅ Single Sign-On (SSO)
- ✅ Email support
- ✅ Access to all endpoints
- ✅ Alert management
- ✅ Quota monitoring

**Best For:** Small businesses and moderate-volume applications

---

### Pro Tier
**Price:** $175/month

**Limits:**
- 280 requests per minute
- 78,000 requests per month
- 15 API keys
- 50 BINs per batch request

**Features:**
- ✅ Data encryption
- ✅ Single Sign-On (SSO)
- ✅ Priority email support
- ✅ Access to all endpoints
- ✅ Advanced alert management
- ✅ Detailed quota monitoring
- ✅ Webhook notifications

**Best For:** Growing businesses with high-volume needs

---

### Enterprise Tier
**Price:** $980/month

**Limits:**
- 768 requests per minute
- **Unlimited** requests per month
- 190 API keys
- 50 BINs per batch request

**Features:**
- ✅ Data encryption
- ✅ Single Sign-On (SSO)
- ✅ Dedicated email support
- ✅ Access to all endpoints
- ✅ Advanced alert management
- ✅ Comprehensive quota monitoring
- ✅ Webhook notifications
- ✅ Priority feature requests
- ✅ Custom integration support

**Best For:** Large enterprises with unlimited volume requirements

---

## Rate Limiting

### Rate Limit Headers
BinSearchLookup uses a sliding window rate limiting algorithm. Each response includes rate limit information:

- Requests are counted per minute and per month
- Exceeding rate limits returns HTTP 429 (Too Many Requests)
- Rate limits reset at the times specified in `/api/quota` endpoint

### Rate Limit Best Practices
1. **Monitor your usage** with the `/api/quota` endpoint
2. **Set up alerts** to notify you before hitting limits
3. **Implement exponential backoff** for retry logic
4. **Cache responses** when appropriate (respect `cached` field)
5. **Use batch endpoints** to optimize request counts
6. **Upgrade your tier** if consistently hitting limits

### Example Rate Limit Error
```json
{
  "error": "Rate limit exceeded. Try again in 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 45
}
```

---

## Error Codes

### Authentication Errors (401)

| Error Code | Description | Solution |
|------------|-------------|----------|
| `MISSING_API_KEY` | X-API-Key header is missing | Include X-API-Key header in request |
| `MISSING_USER_ID` | X-User-ID header is missing | Include X-User-ID header in request |
| `INVALID_API_KEY_FORMAT` | API key format is invalid | Use format: bsl_[64 characters] |
| `INVALID_USER_ID_FORMAT` | User ID format is invalid | Use UUID format |
| `UNAUTHORIZED` | Invalid API key or user ID | Verify credentials in dashboard |

### Request Errors (400)

| Error Code | Description | Solution |
|------------|-------------|----------|
| `MISSING_BIN_PARAMETER` | BIN parameter not provided | Include bin parameter in query string |
| `INVALID_BIN` | BIN format is invalid | Use 6-8 digit BIN numbers |
| `BATCH_SIZE_EXCEEDED` | Too many BINs in batch request | Limit batch to 50 BINs maximum |
| `INVALID_JSON` | Request body is not valid JSON | Check JSON syntax |

### Authorization Errors (403)

| Error Code | Description | Solution |
|------------|-------------|----------|
| `ACCESS_DENIED` | Insufficient permissions | Check user permissions |
| `NO_SUBSCRIPTION` | No active subscription | Subscribe to a plan |
| `SUBSCRIPTION_INACTIVE` | Subscription is not active | Renew subscription |
| `SUBSCRIPTION_EXPIRED` | Subscription has expired | Renew subscription |

### Rate Limit Errors (429)

| Error Code | Description | Solution |
|------------|-------------|----------|
| `RATE_LIMIT_EXCEEDED` | Too many requests | Wait for rate limit window to reset |

### Server Errors (500)

| Error Code | Description | Solution |
|------------|-------------|----------|
| `INTERNAL_ERROR` | Internal server error | Contact support if persistent |
| `DATABASE_ERROR` | Database connection issue | Check status page and retry |

### Error Response Format
```json
{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": "Additional context (optional)"
}
```

---

## Webhooks

BinSearchLookup supports webhooks for real-time event notifications. Configure webhook endpoints in your dashboard to receive notifications about:

- **Usage alerts triggered** - When your usage exceeds configured thresholds
- **Rate limit warnings** - When approaching rate limits
- **Subscription events** - Changes to your subscription status
- **API key events** - API key creation, rotation, or deletion

### Webhook Configuration
1. Navigate to Settings → Webhooks in your dashboard
2. Click "Add Webhook Endpoint"
3. Enter your endpoint URL (must be HTTPS)
4. Select events to subscribe to
5. Save and test your webhook

### Webhook Payload Format
```json
{
  "event": "alert.triggered",
  "timestamp": "2025-10-14T12:00:00Z",
  "data": {
    "alert_type": "month",
    "threshold": 50000,
    "current_usage": 51234,
    "account_id": "your-user-id"
  }
}
```

### Webhook Security
- All webhook requests include an `X-Webhook-Signature` header
- Verify signatures using your webhook secret (found in dashboard)
- Webhooks use HMAC-SHA256 for signature verification

---

## Code Examples

### cURL
```bash
# Single lookup
curl -X GET \
  "https://api.binsearchlookup.com/lookup?bin=551029" \
  -H "X-API-Key: bsl_your_api_key_here" \
  -H "X-User-ID: your-user-id-here"

# Batch lookup
curl -X POST \
  "https://api.binsearchlookup.com/lookup/batch" \
  -H "X-API-Key: bsl_your_api_key_here" \
  -H "X-User-ID: your-user-id-here" \
  -H "Content-Type: application/json" \
  -d '{"bins": ["551029", "411111", "371449"]}'
```

### Node.js
```javascript
const https = require('https');

const options = {
  hostname: 'api.binsearchlookup.com',
  path: '/lookup?bin=551029',
  method: 'GET',
  headers: {
    'X-API-Key': 'bsl_your_api_key_here',
    'X-User-ID': 'your-user-id-here'
  }
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => { console.log(JSON.parse(data)); });
});

req.on('error', (error) => { console.error(error); });
req.end();
```

### Python
```python
import requests

url = "https://api.binsearchlookup.com/lookup"
params = {"bin": "551029"}
headers = {
    "X-API-Key": "bsl_your_api_key_here",
    "X-User-ID": "your-user-id-here"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```

### PHP
```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.binsearchlookup.com/lookup?bin=551029",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: bsl_your_api_key_here",
    "X-User-ID: your-user-id-here"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
?>
```

---

## Best Practices

### Performance Optimization
1. **Use batch endpoints** - Process multiple BINs in one request
2. **Implement caching** - Cache responses based on your use case
3. **Check the `cached` field** - API may return cached data for performance
4. **Monitor `responseTime`** - Track API performance metrics

### Error Handling
1. **Implement retry logic** - Use exponential backoff for transient errors
2. **Log all errors** - Include request IDs for support inquiries
3. **Handle rate limits gracefully** - Respect `retryAfter` values
4. **Validate input** - Check BIN format before making requests

### Security
1. **Never expose API keys** - Use environment variables
2. **Rotate keys regularly** - Especially after team member changes
3. **Use HTTPS only** - Never make requests over HTTP
4. **Implement IP whitelisting** - If your infrastructure supports it
5. **Monitor API key usage** - Watch for suspicious activity

### Integration Tips
1. **Test in free tier first** - Validate integration before upgrading
2. **Set up monitoring** - Use the `/health` endpoint for uptime checks
3. **Configure alerts** - Get notified before hitting quotas
4. **Use webhooks** - For real-time event notifications
5. **Keep documentation handy** - Bookmark the API docs

---

## Support & Resources

### Getting Help
- **Email Support:** contact@binsearchlookup.com
- **Response Time:** Within 24-48 hours for Free/Starter, priority for Pro/Enterprise
- **Status Page:** https://stats.uptimerobot.com/fEv8yBZBFb

### When Contacting Support
Please include:
1. Your User ID (not your API key)
2. Request timestamp
3. Request/Response examples (redact sensitive data)
4. Error messages and codes
5. Steps to reproduce the issue

### Additional Resources
- **Dashboard:** https://www.binsearchlookup.com/login
- **API Documentation:** Available in your dashboard
- **Status Monitoring:** Real-time uptime at stats.uptimerobot.com

---

## Changelog & Updates

### Current Version
The BinSearchLookup API is continuously updated with new BINs and improved data quality. Check the status page for maintenance windows.

### Database Updates
- Database is updated dynamically as needed
- Quality control checks run before each response
- Missing or inconsistent data is automatically flagged for review
- No downtime required for database updates

---

## FAQ

**Q: How quickly can I start using the API after signing up?**  
A: Immediately! There is no DNS propagation or latency delay. Create your API key and start making requests right away.

**Q: What happens if I exceed my rate limit?**  
A: You'll receive a 429 error with a `retryAfter` value indicating when you can retry. Consider upgrading your tier if this happens frequently.

**Q: Can I upgrade or downgrade my plan anytime?**  
A: Yes, you can change your subscription tier from your dashboard at any time. Changes take effect immediately.

**Q: What if a BIN lookup returns no data?**  
A: The API will return a response indicating the lookup was unsuccessful. This may mean the BIN is not in the database yet. Contact support to request adding specific BINs.

**Q: Do you offer refunds?**  
A: Please contact support at contact@binsearchlookup.com to discuss refund policies.

**Q: Is there an SLA for uptime?**  
A: Monitor real-time uptime at https://stats.uptimerobot.com/fEv8yBZBFb. For Enterprise customers, custom SLAs can be discussed.

**Q: Can I get historical data or analytics?**  
A: Your dashboard provides usage analytics. For custom reporting, contact Enterprise support.

**Q: How is my data protected?**  
A: We use encryption for email/password storage, HTTPS for all API traffic, and comply with GDPR, CCPA, PIPEDA, LGPD, and Quebec Bill 25. Payment processing uses Stripe (PCI-DSS Level 1).

---

## Legal & Privacy

### Terms of Service
By using the BinSearchLookup API, you agree to our Terms of Service available at www.binsearchlookup.com/terms

### Privacy Policy
Read our Privacy Policy at www.binsearchlookup.com/privacy

### Data Retention
- API request logs: 90 days
- Usage statistics: Indefinite (aggregated)
- Account data: Until account deletion

### Compliance
BinSearchLookup is compliant with:
- GDPR (European Union)
- CCPA (California, USA)
- PIPEDA (Canada)
- LGPD (Brazil)
- Quebec Bill 25 (Quebec, Canada)

---

**Last Updated:** October 14, 2025  
**API Version:** v1  
**Document Version:** 1.0.0