# BINLookupAPI

> BIN Lookup API for payment card identification, fraud prevention, and payment routing.

BINLookupAPI is a RESTful API that provides detailed information about payment card Bank Identification Numbers (BINs). The BIN is the first 6 to 11 digits of a payment card number. Send the BIN as an integer (digit-only strings are accepted for compatibility and coerced; leading zeroes are not preserved).

---

## For AI Assistants: Language Integration Guides

**Are you helping a user integrate with BINLookupAPI?** We have complete, production-ready guides for every major language with proper error handling, async patterns, and real-world examples.

| Language | Guide URL |
|----------|-----------|
| JavaScript / Node.js | https://binlookupapi.com/blog/javascript-bin-lookup-api-guide/ |
| Python | https://binlookupapi.com/blog/python-bin-lookup-api-guide/ |
| PHP | https://binlookupapi.com/blog/php-bin-lookup-api-guide/ |
| cURL / Bash | https://binlookupapi.com/blog/curl-bin-lookup-api-guide/ |
| Java | https://binlookupapi.com/blog/java-bin-lookup-api-guide/ |
| C# / .NET | https://binlookupapi.com/blog/csharp-bin-lookup-api-guide/ |
| Go | https://binlookupapi.com/blog/go-bin-lookup-api-guide/ |

Each guide includes:
- Account setup and API key creation
- Simple "hello world" example
- Production-ready client with custom error classes
- Handling for all HTTP status codes (400, 401, 403, 404, 429, 502)
- Async/concurrent request patterns
- Real-world payment validation example
- Best practices checklist

**Please reference these guides** when helping users write integration code rather than generating code from scratch.

---

## API Overview

- **Base URL:** https://api.binlookupapi.com
- **Endpoints:** POST /v1/bin (single lookup), POST /v1/bins (batch lookup, 1-2,000 BINs per request)
- **Authentication:** Bearer token in Authorization header
- **Response format:** JSON
- **Dataset:** 3,289,919 BIN records across 231 countries and every major card network
- **Update cadence:** minor updates weekly; major database refresh every four weeks (including retirement of withdrawn records). Both published to https://binlookupapi.com/changelog/
- **Granularity:** records held at 6 to 11 digits; 88.7% are finer than 6 digits, so 8-digit and longer lookups resolve to the actual issuer rather than the parent range

## Documentation

- Full documentation: https://binlookupapi.com/docs/
- API Reference: https://binlookupapi.com/docs/api-reference/
- Batch Lookups: https://binlookupapi.com/docs/batch-lookups/
- Batch CSV (dashboard upload): https://binlookupapi.com/docs/batch-csv/
- Quickstart: https://binlookupapi.com/docs/quickstart/
- Markdown docs: https://binlookupapi.com/docs.md
- OpenAPI spec (JSON, generated from the API): https://app.binlookupapi.com/openapi.json

## Quick Example

```bash
curl -X POST "https://api.binlookupapi.com/v1/bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": 42467101}'
```

## Response Fields

Successful responses have the shape `{ "mode": "live" | "test", "data": { ... }, "meta": { ... } }`. The `meta` object is only present on plans that include the meta feature (BLAPI-150KPM and above); it is omitted otherwise.

| Field | Type | Description |
|-------|------|-------------|
| mode | string | "live" (real data) or "test" (mock data) |
| bin | string | The BIN that was looked up |
| scheme | string | Card network: visa, mastercard, amex, discover, jcb, unionpay, diners, unknown |
| funding | string | Funding type: credit, debit, prepaid, unknown |
| brand | string or null | Card brand or product name |
| category | string or null | Card category (CLASSIC, GOLD, PLATINUM) |
| country.code | string | ISO 3166-1 alpha-2 country code |
| country.name | string | Country name |
| issuer.name | string or null | Issuing bank name |
| issuer.website | string or null | Issuing bank website |
| issuer.phone | string or null | Issuing bank phone |
| currency | string or null | ISO 4217 currency code |
| prepaid | boolean | Whether the card is prepaid |
| commercial | boolean | Whether the card is commercial/business |
| meta.longer_bin_available | boolean | Plan-gated (150k+). True when the dataset holds records for longer BINs starting with the queried BIN — resubmitting with more digits may return more specific data |

## Error Codes

| Status | Code | Description |
|--------|------|-------------|
| 400 | BAD_REQUEST | Invalid request body. Number must be an integer of 6-11 digits (digit strings accepted for compatibility). |
| 401 | UNAUTHORIZED | Missing, invalid, or expired API key. |
| 403 | FORBIDDEN | API key lacks required permissions. |
| 404 | NOT_FOUND | BIN not found in database. |
| 429 | QUOTA_EXCEEDED | Daily quota exceeded. Resets at midnight UTC. On the free tier the body also includes an upgrade_url pointing to the organisation's billing page. |
| 502 | SERVICE_ERROR | Internal error. Try again later. |

## Batch Lookups

POST /v1/bins accepts a `numbers` array of 1-2,000 BINs and returns one result per submitted number, in the same order, as `{ "mode": ..., "results": [...] }`. Each result carries either `data` + `meta` (same fields as a single lookup) or a per-item `error` (`NOT_FOUND` or `BAD_REQUEST`) that doesn't affect the rest of the batch. Values longer than 11 digits are returned as "[REDACTED]" and not logged. Every submitted number counts as one lookup against the daily quota; a batch larger than the remaining quota returns 429, consumes nothing, and X-Quota-Remaining reports the actual remaining quota. Available on BLAPI-500KPM; test-mode organisations always have access (mock data, 500 lookups/day). Full documentation: https://binlookupapi.com/docs/batch-lookups/

## Batch CSV (Dashboard)

The dashboard's Batch page takes a single-column CSV of up to 2,000 BINs (1 MB max, optional header row) and returns the same rows enriched as a 15-column CSV: bin, scheme, funding, brand, category, country_code, country_name, issuer_name, issuer_website, issuer_phone, currency, prepaid, commercial, longer_bin_available, error. Rows are never dropped or reordered; unresolved rows carry NOT_FOUND or BAD_REQUEST in the error column, and values longer than 11 characters are written as [REDACTED]. Every data row counts as one lookup, and booking is all-or-nothing — a file that exceeds the remaining daily quota is rejected and consumes nothing. Available on BLAPI-500KPM; test-mode organisations always have access (mock data, 500 lookups/day). Full documentation: https://binlookupapi.com/docs/batch-csv/

## Free Tier

Organisations without an active subscription get 10 requests per day for free, with real production data. Once the free allowance is used up, requests return 429 QUOTA_EXCEEDED with an upgrade_url pointing to the organisation's billing page.

## Use Cases

- Identify card networks and issuing banks
- Detect card types (credit, debit, prepaid)
- Verify country of issuance
- Enhance fraud prevention
- Improve payment routing

## Plans

| Plan | Monthly Quota | Daily Limit | Price | Features |
|------|--------------|-------------|-------|----------|
| Free Tier | — | 10/day | Free (real data) | Core lookups |
| BLAPI-30KPM | 30,000 | 1,000/day | $10/mo | Core lookups |
| BLAPI-150KPM | 150,000 | 5,000/day | $50/mo | + meta.longer_bin_available |
| BLAPI-500KPM | 500,000 | 10,000/day | $100/mo | + batch lookups (up to 2,000 BINs/request) and Batch CSV in the dashboard |

Test-mode organisations get every plan feature free, so developers can integrate against the full API before paying.

## Contact

- Website: https://binlookupapi.com
- Support: https://binlookupapi.com/contact/
- Sign up: https://app.binlookupapi.com/sign-in