# BINLookupAPI documentation This file lists every documentation page. Each page is also available as its own Markdown file. HTML hub: https://binlookupapi.com/docs/ Agent index: https://binlookupapi.com/llms.txt ## API - [Overview](https://binlookupapi.com/docs/): BIN lookup API documentation. Integrate card issuer identification, BIN validation, fraud prevention, and payment routing with a single REST endpoint. Markdown: https://binlookupapi.com/docs/index.md - [Quickstart](https://binlookupapi.com/docs/quickstart/): Get started with the BIN lookup API in minutes. Create an account, generate an API key, and make your first BIN lookup request with cURL in four steps. Markdown: https://binlookupapi.com/docs/quickstart.md - [API Reference](https://binlookupapi.com/docs/api-reference/): Complete BIN lookup REST API reference. POST /v1/bin endpoint, request parameters, JSON response fields, error codes, and code examples in 7 languages. Markdown: https://binlookupapi.com/docs/api-reference.md - [Batch Lookups](https://binlookupapi.com/docs/batch-lookups/): Bulk BIN lookup endpoint: check up to 2,000 BINs in a single API request. Request format, per-item errors, quota accounting, and code examples. Markdown: https://binlookupapi.com/docs/batch-lookups.md - [Batch CSV](https://binlookupapi.com/docs/batch-csv/): Upload a CSV of up to 2,000 BINs in the dashboard and download an enriched file with scheme, issuer, country, and card flags. No code required. Markdown: https://binlookupapi.com/docs/batch-csv.md ## Support - [Overview](https://binlookupapi.com/docs/support/): Billing, dashboard, API keys, team settings, data definitions, security, and troubleshooting for BINLookupAPI. Markdown: https://binlookupapi.com/docs/support.md - [Billing](https://binlookupapi.com/docs/subscriptions/): BIN lookup API plans and rate limits. Start free with 10 real lookups per day, then compare paid plans by monthly quota and features. Markdown: https://binlookupapi.com/docs/subscriptions.md - [Dashboard](https://binlookupapi.com/docs/support/dashboard/): How to read the BINLookupAPI dashboard home page, Usage page, banners, and organisation settings. Markdown: https://binlookupapi.com/docs/support/dashboard.md - [API Keys](https://binlookupapi.com/docs/api-keys/): Authenticate BIN lookup API requests. Generate a free API key, rotate credentials securely, and use Bearer token authentication. Markdown: https://binlookupapi.com/docs/api-keys.md - [Team](https://binlookupapi.com/docs/support/team/): Invite teammates, accept an invitation, change roles, and transfer ownership of a BINLookupAPI organisation. Markdown: https://binlookupapi.com/docs/support/team.md - [Data](https://binlookupapi.com/docs/support/data/): Where BINLookupAPI BIN data comes from, what response fields mean, and how to report incorrect data. Markdown: https://binlookupapi.com/docs/support/data.md - [Security](https://binlookupapi.com/docs/support/security/): What BINLookupAPI stores about API keys and requests, card-number rules, service providers, and how to delete an organisation. Markdown: https://binlookupapi.com/docs/support/security.md - [Troubleshooting](https://binlookupapi.com/docs/support/troubleshooting/): Causes and corrections for BIN lookup HTTP errors, quota errors, CSV upload failures, and billing problems. Markdown: https://binlookupapi.com/docs/support/troubleshooting.md - [Contact](https://binlookupapi.com/docs/support/contact/): How to contact BINLookupAPI support, what to include in a request, and the response time for each plan. Markdown: https://binlookupapi.com/docs/support/contact.md ## Guides - [All guides](https://binlookupapi.com/docs/guides/): Language guides for the BIN Lookup API. Examples for curl, JavaScript, Python, PHP, Java, C#, and Go use the current POST /v1/bin endpoint. Markdown: https://binlookupapi.com/docs/guides.md - [curl](https://binlookupapi.com/docs/guides/curl/): Call the BIN Lookup API with curl. Send one BIN, read quota headers, and send a batch of up to 2,000 BINs. Markdown: https://binlookupapi.com/docs/guides/curl.md - [JavaScript](https://binlookupapi.com/docs/guides/javascript/): Call the BIN Lookup API from Node.js with fetch. Handle current error codes and send a batch lookup. Markdown: https://binlookupapi.com/docs/guides/javascript.md - [Python](https://binlookupapi.com/docs/guides/python/): Call the BIN Lookup API from Python with requests. Handle current error codes and send a batch lookup. Markdown: https://binlookupapi.com/docs/guides/python.md - [PHP](https://binlookupapi.com/docs/guides/php/): Call the BIN Lookup API from PHP with cURL. Handle current error codes and send a batch lookup. Markdown: https://binlookupapi.com/docs/guides/php.md - [Java](https://binlookupapi.com/docs/guides/java/): Call the BIN Lookup API from Java 11 or later with HttpClient. Handle current error codes and send a batch lookup. Markdown: https://binlookupapi.com/docs/guides/java.md - [C#](https://binlookupapi.com/docs/guides/csharp/): Call the BIN Lookup API from C# with HttpClient. Handle current error codes and send a batch lookup. Markdown: https://binlookupapi.com/docs/guides/csharp.md - [Go](https://binlookupapi.com/docs/guides/go/): Call the BIN Lookup API from Go with net/http. Handle current error codes and send a batch lookup. Markdown: https://binlookupapi.com/docs/guides/go.md --- --- title: "BIN Lookup API Documentation" description: "BIN lookup API documentation. Integrate card issuer identification, BIN validation, fraud prevention, and payment routing with a single REST endpoint." section: "API" url: "https://binlookupapi.com/docs/" markdown_url: "https://binlookupapi.com/docs/index.md" --- # BIN Lookup API Documentation This is the documentation hub for BINLookupAPI. Use one section for the task that you have. | Section | Use it for | |---------|------------| | [API](/docs/api-reference/) | The request format, the response fields, and the error codes. | | [Support](/docs/support/) | Billing, the dashboard, API keys, the team, and account settings. | | [Guides](/docs/guides/) | Working examples in curl, JavaScript, Python, PHP, Java, C#, and Go. | ## What the API returns BINLookupAPI returns data for a Bank Identification Number (BIN). A BIN is the first 6 to 11 digits of a payment card number. You can use a response to: - Identify the card network and the issuing bank. - Identify the funding type: credit, debit, or prepaid. - Read the country that issued the card. The dataset has 3,289,919 BIN records from 231 countries. Records use 6 to 11 digits. 88.7% of the records are longer than 6 digits. Send 8 or more digits when you can. The result is then the issuer range, not only the parent range. ## Data updates | Cadence | What changes | |---------|----------------| | Each week | Small updates. These updates add new ranges and correct records. | | Every 4 weeks | A full refresh. This refresh also removes withdrawn records. | Each refresh is on the [changelog](/changelog/). The API always returns the current data. There is no file to download. ## Endpoints Send every API request to `https://api.binlookupapi.com`. The dashboard host does not accept API requests. | Method and path | Use | |-----------------|-----| | `POST /v1/bin` | Look up one BIN. | | `POST /v1/bins` | Look up 1 to 2,000 BINs in one request. | ## 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}' ``` A success response has this shape: ```json { "mode": "live", "data": { "bin": "42467101", "scheme": "visa", "funding": "debit", "brand": "VISA", "category": "CLASSIC", "country": { "code": "PL", "name": "POLAND" }, "issuer": { "name": "ING BANK SLASKI SA", "website": null, "phone": null }, "currency": "PLN", "prepaid": false, "commercial": false } } ``` Plans BLAPI-150KPM and BLAPI-500KPM also return a `meta` object. See the [API reference](/docs/api-reference/#the-meta-object). ## Where to go next 1. [Create an account and send the first request](/docs/quickstart/). 2. Read the [API reference](/docs/api-reference/) before you handle errors in code. 3. Open the [guide for your language](/docs/guides/). 4. When you need a higher daily limit, open [Billing](/docs/subscriptions/). ## Related pages - [Quickstart](/docs/quickstart/) - [API reference](/docs/api-reference/) - [Language guides](/docs/guides/) - [Billing](/docs/subscriptions/) - [Support overview](/docs/support/) --- --- title: "BIN API Quickstart — First Request in 4 Steps" description: "Get started with the BIN lookup API in minutes. Create an account, generate an API key, and make your first BIN lookup request with cURL in four steps." section: "API" url: "https://binlookupapi.com/docs/quickstart/" markdown_url: "https://binlookupapi.com/docs/quickstart.md" --- # BIN Lookup API Quickstart Follow these steps to send your first BIN lookup. ## 1. Create an account and an organisation You need a Google account or a Microsoft account. BINLookupAPI does not use a password. 1. Open [https://app.binlookupapi.com/sign-in](https://app.binlookupapi.com/sign-in). 2. Select Google or Microsoft. 3. Complete the sign-in steps of that provider. On the first sign-in, the dashboard shows the Create Organisation form. 1. Enter the name of your organisation. 2. Select Create Organisation. The new organisation starts on the free tier. The free tier includes 10 real lookups each day. You do not need a payment card. If you have an invitation, accept it. You then join that organisation. You do not create a new one. See [Accept an invitation](/docs/support/team/#accept-an-invitation). ## 2. Create an API key 1. Open API Keys. 2. Enter a name for the key. Use 1 to 100 characters. Example: `Development`. 3. Select Create Key. 4. Copy the key and store it in a safe place. CAUTION: The dashboard shows the full key one time only. You cannot see the full key again. The key starts with `blapi_live_`. The dashboard then shows a curl command that contains the new key. Only an owner or a developer can create keys. See [API keys](/docs/api-keys/). ## 3. Send the first request The free tier returns real production data. The limit is 10 requests each day. ```bash curl -X POST "https://api.binlookupapi.com/v1/bin" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"number": 42467101}' ``` Replace `YOUR_API_KEY` with your key. A success response looks like this: ```json { "mode": "live", "data": { "bin": "42467101", "scheme": "visa", "funding": "debit", "brand": "VISA", "category": "CLASSIC", "country": { "code": "PL", "name": "POLAND" }, "issuer": { "name": "ING BANK SLASKI SA", "website": null, "phone": null }, "currency": "PLN", "prepaid": false, "commercial": false } } ``` Field definitions are in the [API reference](/docs/api-reference/#response-fields). ## 4. Confirm the request on the Usage page 1. Open Usage. 2. Find the request in the request history. The history columns are time, BIN, API key, HTTP status, and response time. See the [dashboard page](/docs/support/dashboard/#usage-page). ## When you need more than 10 lookups An owner or a billing manager can subscribe on the Billing page. The new daily limit is active immediately. See [Billing](/docs/subscriptions/). ## Language guides | Language | Guide | |----------|-------| | curl | [curl guide](/docs/guides/curl/) | | JavaScript | [JavaScript guide](/docs/guides/javascript/) | | Python | [Python guide](/docs/guides/python/) | | PHP | [PHP guide](/docs/guides/php/) | | Java | [Java guide](/docs/guides/java/) | | C# | [C# guide](/docs/guides/csharp/) | | Go | [Go guide](/docs/guides/go/) | ## Related pages - [API reference](/docs/api-reference/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) - [Language guides](/docs/guides/) --- --- title: "BIN API Reference — Endpoints, Fields & Errors" description: "Complete BIN lookup REST API reference. POST /v1/bin endpoint, request parameters, JSON response fields, error codes, and code examples in 7 languages." section: "API" url: "https://binlookupapi.com/docs/api-reference/" markdown_url: "https://binlookupapi.com/docs/api-reference.md" --- # BIN Lookup API Reference This page is the specification for the BIN Lookup API. The base URL is `https://api.binlookupapi.com`. Send API requests to this host only. The dashboard host does not accept API requests. | Method and path | Use | |-----------------|-----| | `POST /v1/bin` | Look up one BIN. This page documents this endpoint. | | `POST /v1/bins` | Look up 1 to 2,000 BINs. See [Batch lookups](/docs/batch-lookups/). | The machine-readable specification is the [OpenAPI file](https://app.binlookupapi.com/openapi.json). The API generates this file. Import it into Postman, Insomnia, or a code generator. You can also fork the public Postman collection: Language examples are in the [guides](/docs/guides/). ## Authentication Send the API key in the `Authorization` header. Use the Bearer scheme. ```text Authorization: Bearer YOUR_API_KEY ``` Create the key on the API Keys page. See [API keys](/docs/api-keys/). | HTTP status | Error code | Cause | |-------------|------------|-------| | 401 | `UNAUTHORIZED` | The header is missing, or the key is not valid, revoked, or expired. | | 403 | `FORBIDDEN` | The key does not have permission for this endpoint. | ## Look up one BIN Send `POST /v1/bin` with a JSON body. The body has one field, `number`. ```bash curl -X POST "https://api.binlookupapi.com/v1/bin" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"number": 42467101}' ``` ```json { "number": 42467101 } ``` Rules for `number`: - Send the first 6 to 11 digits of the card number. - Send an integer from `100000` to `99999999999`. - A string of digits is also accepted. The API converts it to an integer. - Leading zeros are removed. `"04246710"` is the same value as `4246710`. - The JSON body must be 1 KB or smaller. - Do not send a full card number. See [Card numbers](/docs/support/security/#card-numbers). ## Response fields A success response has HTTP status 200. ```json { "mode": "live", "data": { "bin": "42467101", "scheme": "visa", "funding": "debit", "brand": "VISA", "category": "CLASSIC", "country": { "code": "PL", "name": "POLAND" }, "issuer": { "name": "ING BANK SLASKI SA", "website": null, "phone": null }, "currency": "PLN", "prepaid": false, "commercial": false } } ``` `mode` is `live` or `test`. A test-mode organisation receives mock data. `mode` is then `test`. | Field | Type | Meaning | |-------|------|---------| | `bin` | string | The BIN that matched the request. | | `scheme` | string | `visa`, `mastercard`, `amex`, `discover`, `jcb`, `unionpay`, `diners`, or `unknown`. | | `funding` | string | `credit`, `debit`, `prepaid`, or `unknown`. `credit` includes a charge card. | | `brand` | string or null | The product name. Examples: `VISA`, `PLATINUM`. | | `category` | string or null | The product level. Examples: `CLASSIC`, `GOLD`, `PLATINUM`. | | `country.code` | string | The ISO 3166-1 alpha-2 code of the issuing country. | | `country.name` | string | The name of the issuing country. | | `issuer.name` | string or null | The name of the issuing bank. | | `issuer.website` | string or null | The website of the issuing bank. | | `issuer.phone` | string or null | The phone number of the issuing bank, in international format when known. | | `currency` | string or null | The ISO 4217 code of the issuing country. This is not always the currency of the card account. | | `prepaid` | boolean | `true` when the card is a prepaid card. | | `commercial` | boolean | `true` when the card is a business card or a corporate card. | `brand`, `category`, `currency`, and the issuer fields can be `null`. A null value means the data source has no value for that BIN. The `data` object always contains every field in the table. If a field is absent, [contact support](/docs/support/contact/) and include the BIN and the request time. More detail on currency, issuer contact data, and data sources is on the [data page](/docs/support/data/). ## The meta object BLAPI-150KPM and BLAPI-500KPM add a `meta` object to a success response. A test-mode organisation also receives `meta`. The `data` object is unchanged. `meta` is added next to it: ```json "meta": { "longer_bin_available": true } ``` | Field | Type | Meaning | |-------|------|---------| | `meta.longer_bin_available` | boolean | `true` when the dataset has a longer record that starts with this BIN. | On the free tier and on BLAPI-30KPM, the response does not contain `meta`. The API does not return `null` and does not return an error for this omission. When the value is `true`, send the request again with more digits, up to 11. The second response can be more specific. Do not send more than 11 digits. Example: you send `424671` and `longer_bin_available` is `true`. Send `42467101` next. The second response can use the longer record, and `longer_bin_available` can then be `false`. ## How the API matches a BIN The API returns the longest record that matches the start of the BIN. 1. The API searches for the first 6 digits. 2. The API then searches for 7 digits, then 8 digits, and so on. 3. The search stops at the length that you sent. 4. The API returns the longest matching record. Example: you send `42467101`. The API searches for `424671`, `4246710`, and `42467101`. If a record exists for `42467101`, the API returns that record. If not, it returns `4246710` or `424671`. Send 8 or more digits when you can. Many ranges share the same first 6 digits. ## Errors An error response has this shape: ```json { "error": "QUOTA_EXCEEDED", "message": "Daily request quota exceeded", "upgrade_url": "https://app.binlookupapi.com/organisation/org_.../billing" } ``` `upgrade_url` is not present on every error. When it is present, it opens the Billing page for your organisation. | HTTP status | Error code | Cause | |-------------|------------|-------| | 400 | `BAD_REQUEST` | The body is not valid JSON, a field is missing, the number is out of range, or the body is larger than 1 KB. | | 401 | `UNAUTHORIZED` | The API key is missing, not valid, revoked, or expired. | | 403 | `FORBIDDEN` | The key does not have permission for this endpoint. | | 403 | `FEATURE_NOT_AVAILABLE` | The plan does not include the feature. The message names the required plan. | | 404 | `NOT_FOUND` | No record matches this BIN. | | 429 | `QUOTA_EXCEEDED` | The organisation has used the daily quota. The quota resets at 00:00 UTC. On the free tier, the body includes `upgrade_url`. | | 502 | `SERVICE_ERROR` | An internal error occurred. Send the request again later. | On a [batch request](/docs/batch-lookups/), `NOT_FOUND` and `BAD_REQUEST` are per item. One item error does not stop the other items. A 404 on every request is often a URL problem, not missing BIN data. Use `POST` and the path `/v1/bin` or `/v1/bins` on `https://api.binlookupapi.com`. A body with `"error": "NOT_FOUND"` means the URL is correct and the BIN is not in the data. See [Troubleshooting](/docs/support/troubleshooting/). ## Quota headers Each success response and each 429 response includes these headers: | Header | Meaning | |--------|---------| | `X-Quota-Limit` | The daily limit for the plan. | | `X-Quota-Remaining` | The number of lookups that remain today. | | `X-Quota-Reset` | The next reset time, as a Unix timestamp in seconds. | ```text X-Quota-Limit: 10000 X-Quota-Remaining: 7482 X-Quota-Reset: 1706400000 ``` There is no limit on requests per second. The daily quota is the only limit. Read `X-Quota-Remaining` and stop before it reaches zero. When a single lookup returns 429, `X-Quota-Remaining` is `0`. A batch that is larger than the remaining quota returns 429, uses no quota, and `X-Quota-Remaining` shows the real remainder. See [Billing](/docs/subscriptions/#daily-quota). ## OpenAPI 1. Download [https://app.binlookupapi.com/openapi.json](https://app.binlookupapi.com/openapi.json). 2. Generate a client, or import the file into Postman or Insomnia. 3. Set the base URL to `https://api.binlookupapi.com`. 4. Set the bearer token to your API key. `/openapi.yaml` on this website redirects to that JSON file. ## Stored results BIN data receives small updates each week. You can store a response and reuse it. Refresh a stored result at least once each week. A stored result uses no daily quota. ## Related pages - [Batch lookups](/docs/batch-lookups/) - [Language guides](/docs/guides/) - [Billing and quotas](/docs/subscriptions/) - [API keys](/docs/api-keys/) - [Data definitions](/docs/support/data/) - [Troubleshooting](/docs/support/troubleshooting/) --- --- title: "Bulk BIN Lookup API — 2,000 BINs Per Request" description: "Bulk BIN lookup endpoint: check up to 2,000 BINs in a single API request. Request format, per-item errors, quota accounting, and code examples." section: "API" url: "https://binlookupapi.com/docs/batch-lookups/" markdown_url: "https://binlookupapi.com/docs/batch-lookups.md" --- # Bulk BIN Lookup `POST /v1/bins` looks up many BINs in one request. A batch contains 1 to 2,000 BINs. The response has one result for each value, in the same order. The base URL is `https://api.binlookupapi.com`. ## Availability Batch lookup is included in BLAPI-500KPM. See [Billing](/docs/subscriptions/). On other plans, the API returns HTTP 403 and the error code `FEATURE_NOT_AVAILABLE`. The message names the required plan. The body can include `upgrade_url`. A test-mode organisation can call this endpoint before it subscribes. The response uses mock data. The test-mode daily limit is 500 lookups, so a test batch larger than 500 items returns 429. You can also upload a file in the dashboard. See [Batch CSV](/docs/batch-csv/). ## Request Send a JSON body with a `numbers` array. ```bash curl -X POST "https://api.binlookupapi.com/v1/bins" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"numbers": [400062, "400597", 99999999]}' ``` ```json { "numbers": [400062, "400597", 99999999] } ``` Each value uses the same rules as [one lookup](/docs/api-reference/#look-up-one-bin): - An integer from `100000` to `99999999999`, or a string of digits. - Leading zeros are removed. - Do not send a full card number. - The array length is 1 to 2,000. ## Response ```json { "mode": "live", "results": [ { "number": 400062, "data": { "bin": "400062", "scheme": "visa", "funding": "debit", "brand": "VISA", "category": "SIGNATURE", "country": { "code": "AE", "name": "UNITED ARAB EMIRATES" }, "issuer": { "name": "EMIRATES NBD BANK (P.J.S.C.)", "website": "http://www.emiratesnbd.com/en/", "phone": "+971800456" }, "currency": "AED", "prepaid": false, "commercial": false }, "meta": { "longer_bin_available": true } }, { "number": "400597", "data": { "bin": "400597", "scheme": "visa", "funding": "credit", "brand": "VISA", "category": "BUSINESS", "country": { "code": "US", "name": "UNITED STATES" }, "issuer": { "name": "FIRST ELECTRONIC BANK", "website": "https://firstelectronic.bank/", "phone": "+ (1) 801-572-4004" }, "currency": "USD", "prepaid": false, "commercial": true }, "meta": { "longer_bin_available": true } }, { "number": 99999999, "error": "NOT_FOUND", "message": "BIN not found" } ] } ``` | Field | Type | Meaning | |-------|------|---------| | `mode` | string | `live` or `test`. | | `results[].number` | integer or string | The value that you sent, echoed in the same form. | | `results[].data` | object | The same fields as a single lookup. See the [API reference](/docs/api-reference/#response-fields). | | `results[].meta.longer_bin_available` | boolean | The same signal as on a single lookup. It is omitted when the plan does not include `meta`. | | `results[].error` | string | `NOT_FOUND` or `BAD_REQUEST` when that item failed. | | `results[].message` | string | Text that describes the item error. | ## Item errors One failed item does not change the other items. A failed item has `error` and `message` instead of `data`. | Error code | Cause | |------------|-------| | `NOT_FOUND` | The BIN is not in the dataset. | | `BAD_REQUEST` | The value is not a valid BIN. | The whole request fails only for these causes: | HTTP status | Error code | Cause | |-------------|------------|-------| | 400 | `BAD_REQUEST` | The JSON is not valid, `numbers` is missing, or the array has more than 2,000 values. | | 401 | `UNAUTHORIZED` | The API key is missing, not valid, revoked, or expired. | | 403 | `FEATURE_NOT_AVAILABLE` | The plan does not include batch lookup. | | 403 | `FORBIDDEN` | The key does not have permission for this endpoint. | | 429 | `QUOTA_EXCEEDED` | The batch is larger than the remaining daily quota. | ## Card number redaction A value with more than 11 digits can be a full card number. The API returns that value as `"[REDACTED]"` with item error `BAD_REQUEST`. The API does not store the original value in the request log. ```json { "number": "[REDACTED]", "error": "BAD_REQUEST", "message": "number must be an integer between 6 and 11 digits; digit strings are accepted for compatibility" } ``` ## Quota Each value in the array uses one lookup. This includes values that are not valid and values that are not found. If the batch is larger than the remaining quota, the API returns 429 and uses no quota. `X-Quota-Remaining` then shows the real remainder, not zero. Split the batch and send it again. A single-lookup 429 is different. `X-Quota-Remaining` is then `0`. See [Daily quota](/docs/subscriptions/#daily-quota). ## Related pages - [Batch CSV](/docs/batch-csv/) - [API reference](/docs/api-reference/) - [Language guides](/docs/guides/) - [Billing](/docs/subscriptions/) --- --- title: "Bulk BIN Lookup CSV — Upload, Enrich, Download" description: "Upload a CSV of up to 2,000 BINs in the dashboard and download an enriched file with scheme, issuer, country, and card flags. No code required." section: "API" url: "https://binlookupapi.com/docs/batch-csv/" markdown_url: "https://binlookupapi.com/docs/batch-csv.md" --- # Batch CSV The Batch page accepts a CSV file of BINs and returns a CSV file with one lookup for each row. You do not write code and you do not use an API key for this page. This is the dashboard form of [`POST /v1/bins`](/docs/batch-lookups/). The row limit, the data, and the quota rules are the same. ## Availability Batch CSV is included in BLAPI-500KPM (US$100 per month). See [Billing](/docs/subscriptions/). On other plans, the Batch page shows a preview and does not process the file. Change the plan to BLAPI-500KPM. An upgrade is active immediately. See [Troubleshooting](/docs/support/troubleshooting/#batch-page). A test-mode organisation can use the page with mock data. The test-mode daily limit is 500 lookups. A test file with more than 500 data rows is rejected. Any member of the organisation can use the page. No special role is required. ## Run a batch 1. Sign in at [https://app.binlookupapi.com/](https://app.binlookupapi.com/) and open Batch. 2. Read the remaining daily quota on the page. The whole file must fit in that quota. 3. Drag the CSV file to the upload area, or select the area to choose a file. 4. Select Process CSV. 5. The browser downloads `-enriched.csv`. The page then shows how many rows were found, how many were not found, and how many were not valid. Select Download again to download the same file. The result stays in the browser only. The server does not store the result file. If you leave the page, the result is discarded. ## File rules | Rule | Detail | |------|--------| | File size | 1 MB maximum. | | Rows | 2,000 data rows maximum. | | Columns | One column. Put one BIN on each line. | | Header | Optional. A first row that is not a number, such as `bin`, is a header. The page does not look up a header. | | Encoding | UTF-8. A byte order mark at the start is removed. | | Line endings | `LF`, `CRLF`, and `CR` are accepted. | | Blank lines | Ignored, including blank lines at the end. | | Quotes | A fully quoted cell is accepted (`"400062"`). A doubled quote (`""`) is an escaped quote. | Each value uses the same rules as [one lookup](/docs/api-reference/#look-up-one-bin). The range is 6 to 11 digits, from `100000` to `99999999999`. Leading zeros are not significant. `0400062` is looked up as `400062`. The `bin` column in the result repeats the text that you sent. WARNING: Do not upload full card numbers. A value longer than 11 characters is replaced before it is stored. See [Card number redaction](#card-number-redaction). ### Example input ```csv bin 400062 99999999 invalid 4242424242424242 ``` ## Output columns The result always has these 15 columns, in this order: ```text bin,scheme,funding,brand,category,country_code,country_name,issuer_name,issuer_website,issuer_phone,currency,prepaid,commercial,longer_bin_available,error ``` | Column | Meaning | |--------|---------| | `bin` | The value that you sent. | | `scheme` | The card network, in lower case. Example: `visa`. | | `funding` | `credit`, `debit`, `prepaid`, or `unknown`. | | `brand` | The brand as issued. Example: `VISA`. | | `category` | The product level. Examples: `CLASSIC`, `SIGNATURE`, `BUSINESS`. | | `country_code` | The ISO 3166-1 alpha-2 code. | | `country_name` | The name of the issuing country. | | `issuer_name` | The issuing bank. | | `issuer_website` | The issuer website, when it is known. | | `issuer_phone` | The issuer phone number, when it is known. | | `currency` | The ISO 4217 code of the issuing country. | | `prepaid` | `true` or `false`. | | `commercial` | `true` or `false`. | | `longer_bin_available` | `true` when a longer BIN can match a more specific record. | | `error` | Empty on success. Otherwise `NOT_FOUND` or `BAD_REQUEST`. | An unknown value is an empty cell. Field definitions are in the [API reference](/docs/api-reference/#response-fields). ### Example output ```csv bin,scheme,funding,brand,category,country_code,country_name,issuer_name,issuer_website,issuer_phone,currency,prepaid,commercial,longer_bin_available,error 400062,visa,debit,VISA,SIGNATURE,AE,UNITED ARAB EMIRATES,EMIRATES NBD BANK (P.J.S.C.),http://www.emiratesnbd.com/en/,+971800456,AED,false,false,true, 99999999,,,,,,,,,,,,,,NOT_FOUND invalid,,,,,,,,,,,,,,BAD_REQUEST [REDACTED],,,,,,,,,,,,,,BAD_REQUEST ``` ## Row errors The result has one row for each input row, in the same order. The page does not drop a row and does not reorder rows. | Error code | Cause | |------------|-------| | `NOT_FOUND` | The BIN is valid and is not in the dataset. | | `BAD_REQUEST` | The value is not a valid BIN. It is not numeric, it has fewer than 6 digits, or it has more than 11 characters. | ## Card number redaction A value longer than 11 characters can be a full card number. The `bin` column shows `[REDACTED]` and the error is `BAD_REQUEST`. The original value is not written to the result file or to the request log. ## Quota Each data row uses one lookup. This includes rows with `NOT_FOUND` or `BAD_REQUEST`. A file of 2,000 rows uses 2,000 lookups. The page accepts the whole file or none of it. If the file needs more lookups than the remaining quota, the page does not charge the quota and does not write a request-log entry. The page shows the required count and the remainder: ```text Daily quota exceeded: this file needs 2,000 lookups but only 340 remain today (limit 10,000). ``` Split the file, or wait for the reset at 00:00 UTC. See [Daily quota](/docs/subscriptions/#daily-quota). A successful run is one row on the Usage page. The unit count is the row count. ## Upload errors The page rejects the whole file and does not charge the quota when validation fails. | Message | Cause | |---------|-------| | `Choose a CSV file to upload` | You started the upload with no file. | | `The CSV file must be 1 MB or smaller` | The file is larger than 1 MB. | | `The CSV file is empty` | The file has no content. | | `CSV contains no data rows` | The file has only a header, or only blank lines. | | `CSV has more than 2,000 data rows` | The file has more than 2,000 data rows after the header. | | `line 12 has multiple columns; upload a single-column CSV` | That line has a comma that is not inside quotes. | | `line 12 has malformed quotes` | A quote on that line is not closed, or text follows the closing quote. | | `Lookup backend error` | The lookup service failed. Try again later. If it continues, [contact support](/docs/support/contact/). | The line number is the physical line in the file. ## Batch CSV or the API | | Batch CSV | `POST /v1/bins` | |---|-----------|-----------------| | Interface | Dashboard upload | HTTP request | | Limit | 2,000 BINs | 2,000 BINs | | Output | CSV file, 15 columns | JSON, one object per BIN | | Automation | Manual | A script can run it | | Use it for | A spreadsheet or a one-time file | An application or a repeated job | Both use the same quota rate. Both require BLAPI-500KPM, or a test-mode organisation. ## Related pages - [Batch lookups](/docs/batch-lookups/) - [API reference](/docs/api-reference/) - [Billing](/docs/subscriptions/) - [Dashboard](/docs/support/dashboard/) - [Troubleshooting](/docs/support/troubleshooting/#csv-upload) --- --- title: "Support & Help Center" description: "Billing, dashboard, API keys, team settings, data definitions, security, and troubleshooting for BINLookupAPI." section: "Support" url: "https://binlookupapi.com/docs/support/" markdown_url: "https://binlookupapi.com/docs/support.md" --- # Support Use these pages to operate an organisation. The request format is in the [API reference](/docs/api-reference/). Code examples are in the [guides](/docs/guides/). | Task | Page | |------|------| | Choose a plan, pay, or read the daily quota | [Billing](/docs/subscriptions/) | | Read the home page, Usage, or organisation settings | [Dashboard](/docs/support/dashboard/) | | Create, revoke, or protect an API key | [API keys](/docs/api-keys/) | | Invite a member or change a role | [Team](/docs/support/team/) | | Understand BIN fields and report bad data | [Data](/docs/support/data/) | | Read what is stored and how to delete an organisation | [Security](/docs/support/security/) | | Correct a failed request or a failed payment | [Troubleshooting](/docs/support/troubleshooting/) | | Contact BINLookupAPI | [Contact](/docs/support/contact/) | ## A normal path 1. [Create an organisation and send one lookup](/docs/quickstart/). 2. Read the [response fields](/docs/api-reference/#response-fields). 3. Add the call to your application with a [language guide](/docs/guides/). 4. When the free tier is not enough, [subscribe](/docs/subscriptions/#subscribe-to-a-plan). 5. Invite the people who manage keys or billing on the [team page](/docs/support/team/). ## Related pages - [Quickstart](/docs/quickstart/) - [Billing](/docs/subscriptions/) - [API reference](/docs/api-reference/) - [Contact](/docs/support/contact/) --- --- title: "BIN Lookup API Free Tier & Plan Quotas" description: "BIN lookup API plans and rate limits. Start free with 10 real lookups per day, then compare paid plans by monthly quota and features." section: "Support" url: "https://binlookupapi.com/docs/subscriptions/" markdown_url: "https://binlookupapi.com/docs/subscriptions.md" --- # Plans and billing This page covers plans, the daily quota, and payments. The API fields that a plan unlocks are in the [API reference](/docs/api-reference/). ## Plans An organisation with no subscription is on the free tier. | | Free tier | BLAPI-30KPM | BLAPI-150KPM | BLAPI-500KPM | |---|-----------|-------------|--------------|--------------| | Price | US$0 | US$20 per month | US$50 per month | US$100 per month | | Lookups per month | — | 30,000 | 150,000 | 500,000 | | Daily limit | 10 | 1,000 | 5,000 | 10,000 | | Data | Production data | Production data | Production data | Production data | | `meta.longer_bin_available` | No | No | Yes | Yes | | Batch lookup and Batch CSV | No | No | No | Yes | | Support | Email, 1 business day | Email, 1 business day | Email, 1 business day | Priority, 8 hours | A higher plan includes the features of the plans below it. There is no charge for use above the daily limit. Requests stop when the organisation reaches the limit. A test-mode organisation can use every plan feature before it pays. The data is mock data. The test-mode daily limit is 500 lookups. If you need more than 10,000 requests each day, see [Higher volumes](#higher-volumes). ## Free tier - The limit is 10 lookups each day. - The data is the same production data as a paid plan. - The dashboard is available. - You do not need a payment card. When the 10 lookups are used, the API returns HTTP 429 and `QUOTA_EXCEEDED`. The body includes `upgrade_url`. That URL opens the Billing page for the organisation. ## Daily quota The plan name shows a monthly count. The API enforces a daily limit. Example: BLAPI-30KPM allows 1,000 requests each day, not 30,000 in one day. - The counter resets at 00:00 UTC. - Unused requests do not move to the next day. - One single lookup uses one unit. - Each BIN in a batch request uses one unit. - Each data row in a Batch CSV file uses one unit. - All API keys in one organisation share one quota. When the count for the current UTC day reaches the daily limit, the API returns: ```json { "error": "QUOTA_EXCEEDED", "message": "Daily request quota exceeded" } ``` The HTTP status is 429. On the free tier, the body also includes `upgrade_url`. If a batch or a CSV file is larger than the remaining quota, the API uses no quota. See [Batch lookups](/docs/batch-lookups/#quota). After an upgrade, the new daily limit applies immediately. Lookups from earlier in the same day still count. There is no limit on requests per second. The daily quota is the only limit. ### Quota headers Each success response and each 429 response includes: | Header | Meaning | |--------|---------| | `X-Quota-Limit` | The daily limit. | | `X-Quota-Remaining` | The units that remain today. | | `X-Quota-Reset` | The next reset, as a Unix timestamp in seconds. | When a single lookup returns 429, `X-Quota-Remaining` is `0`. When a batch is rejected because it does not fit, `X-Quota-Remaining` is the real remainder. You can also read Remaining on the [dashboard home page](/docs/support/dashboard/). ### Quota emails BINLookupAPI sends two emails: | Subject | When | |---------|------| | `[Organisation] has used 80% of today's API quota` | Usage reaches 80% of the daily limit. | | `[Organisation] has reached its daily API limit` | Usage reaches the daily limit. | Owners and billing managers receive the emails. Each email is sent at most once per day. The sender is `noreply@binlookupapi.com`. You cannot turn these emails off. ## Subscribe to a plan Only an owner or a billing manager can subscribe. See [Roles](/docs/support/team/#roles). 1. Open Billing. 2. Select a plan. 3. Complete the payment form. 4. Return to the dashboard. The new daily limit is active immediately. Payments use Stripe. BINLookupAPI does not store your card details. You can add a tax ID or VAT number on the payment form. You can also add it later in the customer portal. If the Billing page still shows the free tier after payment, wait one minute and refresh the page. Confirm that you are in the correct organisation. See [Troubleshooting](/docs/support/troubleshooting/#payment-not-shown). ## Promotion codes 1. Open Billing. 2. Select a plan. 3. On the payment form, select Add promotion code. 4. Enter the code and complete the payment. If the code fails, check that it has not expired. If it still fails, [contact support](/docs/support/contact/). ## Change your plan 1. Open Billing. 2. Select Change Plan. 3. Select the new plan in the customer portal. 4. Confirm the change. | Change | When it is active | Payment | |--------|-------------------|---------| | Upgrade | Immediately | The difference for the rest of the current period is charged. | | Downgrade | At the start of the next billing period | The next invoice uses the new price. | After an upgrade, the new daily limit applies immediately. Earlier requests from the same day still count. After a downgrade, the current limit continues until the next billing period. ## Cancel a subscription 1. Open Billing. 2. Select Manage billing. 3. In the customer portal, select Cancel subscription. 4. Confirm the cancellation. The plan continues until the end of the current billing period. The Billing page shows `Cancels at period end`. After that time, the organisation returns to the free tier. API keys still work, with a limit of 10 lookups each day. ## Invoices and payment methods Only an owner or a billing manager can open the customer portal. 1. Open Billing. 2. Select Manage billing. In the portal you can: - Download invoices and receipts. - Change the payment method. - Change the billing address. - Add or change a tax ID or VAT number. ## Payment problems ### The last payment failed The banner text is `We couldn't process your last payment`. Stripe tries the payment again, up to 10 times over 30 days. The plan limits stay active during that time. 1. Select Update your payment method in the banner. 2. Enter a valid payment method. ### The subscription has lapsed The banner text is `Your subscription has lapsed`. Every payment attempt failed. The organisation is on the free tier, with 10 lookups each day. 1. Select Update your payment method in the banner. 2. Enter a valid payment method. 3. [Subscribe](#subscribe-to-a-plan) again. Other banners are on the [dashboard page](/docs/support/dashboard/#banners). ## Higher volumes BLAPI-500KPM allows 10,000 requests each day. For a higher limit, use the [contact form](/contact/). Include: - The organisation name. - The number of requests that you need each day. - The features that you need. ## Related pages - [API reference](/docs/api-reference/) - [Batch lookups](/docs/batch-lookups/) - [Dashboard](/docs/support/dashboard/) - [Team roles](/docs/support/team/) - [Troubleshooting](/docs/support/troubleshooting/) - [Contact](/docs/support/contact/) --- --- title: "Dashboard Guide" description: "How to read the BINLookupAPI dashboard home page, Usage page, banners, and organisation settings." section: "Support" url: "https://binlookupapi.com/docs/support/dashboard/" markdown_url: "https://binlookupapi.com/docs/support/dashboard.md" --- # Dashboard The dashboard is at [https://app.binlookupapi.com/](https://app.binlookupapi.com/). Sign in with Google or Microsoft. See the [quickstart](/docs/quickstart/) to create the first organisation. ## Home page The home page shows activity for the current UTC day. | Statistic | Meaning | |-----------|---------| | Requests today | The number of requests since 00:00 UTC. | | Daily quota | The daily limit of the plan. | | Remaining | The number of requests that you can still send today. | | Success rate today | The percentage of requests that returned a success response. | Recent requests shows the last five requests. Each row shows the BIN, the HTTP status, and the response time. The API keys table shows each key and the number of requests for that key. Quick start shows a curl command that you can copy. The command uses a key from this organisation. ## Banners A banner at the top of the dashboard means the organisation needs an action. | Banner | Meaning | Action | |--------|---------|--------| | Free tier | The organisation has no subscription. | [Subscribe](/docs/subscriptions/#subscribe-to-a-plan) for a higher limit. | | Approaching daily limit | Usage is 80% or more of the daily quota. | Send fewer requests, or [upgrade](/docs/subscriptions/#change-your-plan). | | Daily limit reached | The daily quota is used. | Wait until 00:00 UTC, or upgrade. | | Payment failed | The last payment did not complete, or the subscription lapsed. | See [Payment problems](/docs/subscriptions/#payment-problems). | ## Usage page Usage shows API activity for a date range that you select. The summary has four values: - Total requests. - Failed requests. A failed request is any response that is not HTTP 200. - Success rate. - Average response time. The request history has 25 rows per page. | Column | Meaning | |--------|---------| | Time | The time of the request. | | BIN | The BIN that you sent. | | API Key | The name of the key that sent the request. | | Status | The HTTP status of the response. | | Response Time | The time the API took to answer. | Select 7 Days, 30 Days, or All Time. You can also set a start date and an end date. A batch request counts each BIN. A Batch CSV upload is one history row, and the unit count is the row count. See [Batch CSV](/docs/batch-csv/). ## Switch organisation You can belong to more than one organisation. 1. Select the organisation name at the top of the dashboard. 2. Select the organisation in the list. Each organisation has its own API keys, quota, subscription, and members. To create another organisation: 1. Select the organisation name at the top of the dashboard. 2. Select Create organisation. 3. Enter a name. 4. Select Create Organisation. ## Rename an organisation Only an owner can rename an organisation. 1. Open Settings. 2. In Organisation Details, enter the new name. 3. Select Save. The new name appears immediately. ## Batch page On BLAPI-500KPM, open Batch to upload a CSV file. The steps, the file rules, and the output columns are on the [Batch CSV](/docs/batch-csv/) page. On other plans, the page shows a preview only. ## Related pages - [Quickstart](/docs/quickstart/) - [Billing](/docs/subscriptions/) - [API keys](/docs/api-keys/) - [Batch CSV](/docs/batch-csv/) - [Troubleshooting](/docs/support/troubleshooting/) --- --- title: "BIN API Authentication — Keys & Bearer Tokens" description: "Authenticate BIN lookup API requests. Generate a free API key, rotate credentials securely, and use Bearer token authentication." section: "Support" url: "https://binlookupapi.com/docs/api-keys/" markdown_url: "https://binlookupapi.com/docs/api-keys.md" --- # API keys An API key authenticates a request. The key belongs to one organisation. Send it as a bearer token. ```text Authorization: Bearer YOUR_API_KEY ``` ```bash curl -X POST "https://api.binlookupapi.com/v1/bin" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"number": 42467101}' ``` The request rules are in the [API reference](/docs/api-reference/#authentication). ## Who can manage keys | Role | Create | Rename | Revoke | View | |------|--------|--------|--------|------| | Owner | Yes | Yes | Yes | Yes | | Developer | Yes | Yes | Yes | Yes | | Billing manager | No | No | No | Yes | | Member | No | No | No | Yes | Every member can see key names and the first characters of each key. No member can see a full key after it is created. Role definitions are on the [team page](/docs/support/team/#roles). ## Create a key 1. Open API Keys. 2. Enter a name. The name must have 1 to 100 characters. 3. Select Create Key. 4. Copy the key and store it outside the dashboard. CAUTION: The dashboard shows the full key one time only. Keys start with `blapi_live_`. After creation, the table shows the first characters of the key. The dashboard also shows a curl command that contains the new key. ## Key status | Status | Meaning | |--------|---------| | Active | The key works. | | Revoked | A member revoked the key. The key does not work. | | Expired | The key is past an expiry date. The key does not work. | You cannot set an expiry date in the dashboard. A key does not expire unless BINLookupAPI sets an expiry date for you. The table also shows the name, the key prefix, and the creation date. ## Rename, revoke, and rotate ### Rename a key 1. Open API Keys. 2. Select Rename next to the key. 3. Enter the new name. 4. Select Save. ### Revoke a key CAUTION: You cannot undo a revocation. The key stops immediately. 1. Open API Keys. 2. Select Revoke next to the key. 3. Confirm the action. Create a new key when you need a replacement. A revoked key cannot be activated again. ### Rotate a key Use these steps to replace a key without a gap. 1. [Create a new key](#create-a-key). 2. Change the application to use the new key. 3. Confirm that the new key returns HTTP 200. 4. Revoke the old key. If a key is exposed, create a new key, switch the application, and then revoke the exposed key. ## Protect a key - Store the key in an environment variable or a secrets manager. - Do not put the key in source control. - Do not put the key in browser code or in a mobile application. - Create one key for each environment, such as development, staging, and production. - Create one key for each service that calls the API. - Revoke keys that you do not use. All keys in one organisation share the [daily quota](/docs/subscriptions/#daily-quota). A missing or rejected key returns HTTP 401: ```json { "error": "UNAUTHORIZED", "message": "Missing, invalid, revoked, or expired API key" } ``` See [HTTP 401](/docs/support/troubleshooting/#http-401). ## How the key is stored BINLookupAPI stores a hash of the key. The full key is not stored. The dashboard cannot show it again. See [Security](/docs/support/security/#how-we-store-api-keys). ## Related pages - [Quickstart](/docs/quickstart/) - [API reference](/docs/api-reference/) - [Team roles](/docs/support/team/) - [Security](/docs/support/security/) - [JavaScript guide](/docs/guides/javascript/) --- --- title: "Team Roles and Invitations" description: "Invite teammates, accept an invitation, change roles, and transfer ownership of a BINLookupAPI organisation." section: "Support" url: "https://binlookupapi.com/docs/support/team/" markdown_url: "https://binlookupapi.com/docs/support/team.md" --- # Team and roles Each member has one role. The role controls access to settings, API keys, and billing. ## Roles | Role | Access | |------|--------| | Owner | Settings, members, roles, API keys, and billing. | | Developer | Create, rename, and revoke API keys. | | Billing manager | Subscribe, change the plan, and open the customer portal. | | Member | Read-only access to the dashboard, Usage, and API keys. | | Action | Owner | Developer | Billing manager | Member | |--------|-------|-----------|-----------------|--------| | View the dashboard and Usage | Yes | Yes | Yes | Yes | | Manage API keys | Yes | Yes | No | No | | Manage billing | Yes | No | Yes | No | | Invite and remove members | Yes | No | No | No | | Change roles | Yes | No | No | No | | Rename the organisation | Yes | No | No | No | An organisation must have at least one owner. An organisation can have more than one owner. Key actions are also listed on the [API keys](/docs/api-keys/#who-can-manage-keys) page. Billing actions are on the [billing](/docs/subscriptions/) page. ## Invite a member Only an owner can invite a member. 1. Open Settings. 2. In Invite a Member, enter the email address. 3. Select a role. 4. Select Invite. The person receives an email from `noreply@binlookupapi.com`. The invitation is valid for 7 days. After 7 days, send a new invitation. Pending Invitations lists open invitations. Select Cancel to remove one. To send an invitation again, cancel the pending invitation and invite the same email address again. ## Accept an invitation 1. Open the email from BINLookupAPI. 2. Select the link. 3. Sign in with Google or Microsoft. Use the same email address as the invitation. 4. Select Accept. The organisation dashboard opens. To decline, select Decline on the invitation page. You can then create your own organisation. | Message | Meaning | Action | |---------|---------|--------| | Invitation mismatch | You signed in with a different email address. | Sign out. Sign in with the invited address. | | Invitation unavailable | The invitation expired, or a member cancelled it. | Ask an owner for a new invitation. | If the email does not arrive, see [Missing emails](/docs/support/troubleshooting/#missing-emails). ## Change a role or remove a member Only an owner can change roles and remove members. To change a role: 1. Open Settings. 2. In Current Members, find the member. 3. Select the new role. The change is active immediately. To remove a member: 1. Open Settings. 2. In Current Members, find the member. 3. Select Remove. 4. Confirm the action. The member loses access immediately. API keys that the member created still work. Revoke those keys if they must stop. See [Revoke a key](/docs/api-keys/#revoke-a-key). You cannot remove the last owner. You cannot change the role of the last owner. Make another member an owner first. ## Transfer ownership 1. Open Settings. 2. In Current Members, find the new owner. 3. Change that role to Owner. 4. Change your own role, or remove yourself. You can also keep your owner role. More than one owner is allowed. ## Related pages - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) - [Dashboard](/docs/support/dashboard/) - [Security](/docs/support/security/) --- --- title: "BIN Data and Coverage" description: "Where BINLookupAPI BIN data comes from, what response fields mean, and how to report incorrect data." section: "Support" url: "https://binlookupapi.com/docs/support/data/" markdown_url: "https://binlookupapi.com/docs/support/data.md" --- # Data and coverage This page explains the dataset. The field table for a response is in the [API reference](/docs/api-reference/#response-fields). ## Data sources BINLookupAPI gets BIN data from third-party vendors, banks, and the card networks. - The dataset has 3,289,919 BIN records. - Records cover 231 countries. - BIN length is 6 to 11 digits. 88.7% of records are longer than 6 digits. - The data includes more than 80 card brands. - The fields include the brand, the issuer, the card type, the category, the issuing country, and issuer contact details. Small updates ship each week. A full refresh ships every 4 weeks and can remove withdrawn records. Each refresh is on the [changelog](/changelog/). Every plan, including the free tier, reads the same live dataset. ## Scheme, funding, and category `scheme` is the card network: | Value | Network | |-------|---------| | `visa` | Visa | | `mastercard` | Mastercard | | `amex` | American Express | | `discover` | Discover | | `jcb` | JCB | | `unionpay` | UnionPay | | `diners` | Diners Club | | `unknown` | The network is not one of the values above. | `funding` is the funding type: | Value | Meaning | |-------|---------| | `credit` | A credit card or a charge card. | | `debit` | A debit card. | | `prepaid` | A prepaid card. | | `unknown` | The funding type is not known. | `category` is the product level. Examples are `CLASSIC`, `GOLD`, and `PLATINUM`. The value can be `null`. ## Prepaid and commercial | Field | `true` | `false` | |-------|--------|---------| | `prepaid` | The card is a prepaid card. | The card is not a prepaid card. | | `commercial` | The card is a business card or a corporate card. | The card is a personal card. | ## Currency `currency` is the ISO 4217 code of the issuing country. The API does not read the currency from the card account. - If a country changed its currency, the API returns the current code. Example: Germany returns `EUR`, not `DEM`. - The field is `null` when the issuing country is not known. - The currency of the issuing country is not always the currency of the card account. ## Issuer contact details | Field | Meaning | |-------|---------| | `issuer.name` | The name of the bank. | | `issuer.website` | The website of the bank. | | `issuer.phone` | The customer service phone number, in international format when it is known. | Each field can be `null`. Many issuers do not publish a website or a phone number. ## When a BIN is not found The API returns `NOT_FOUND` when no record matches the BIN. Common causes: - The BIN is not in the data. - The card range is new, and the weekly update does not contain it yet. - The number is not a card range. Check the digits, then send more digits, up to 11. Matching rules are in the [API reference](/docs/api-reference/#how-the-api-matches-a-bin). If the error continues, [report the BIN](#report-incorrect-data). ## Report incorrect data If a lookup returns incorrect data, BINLookupAPI checks the sources and corrects the record. Send an email to [support@binlookupapi.com](mailto:support@binlookupapi.com), or use the chat in the dashboard. Include: - The BIN that you sent. - The field that is incorrect. - The correct value, if you know it. - The source of the correct value, if you have one. WARNING: Do not send a full card number in the report. ## Related pages - [API reference](/docs/api-reference/) - [Changelog](/changelog/) - [Security](/docs/support/security/) - [Contact](/docs/support/contact/) --- --- title: "Security and Privacy" description: "What BINLookupAPI stores about API keys and requests, card-number rules, service providers, and how to delete an organisation." section: "Support" url: "https://binlookupapi.com/docs/support/security/" markdown_url: "https://binlookupapi.com/docs/support/security.md" --- # Security and privacy This page states what BINLookupAPI stores and how to ask for a deletion. Key handling for your application is on the [API keys](/docs/api-keys/#protect-a-key) page. ## Card numbers The API needs the first 6 to 11 digits of a card number. Do not send more. - A full card number is sensitive data under PCI DSS. - The API does not need the full number. The first 6 to 11 digits identify the issuer. - The API rejects a `number` value with more than 11 digits. - In a batch response, a value with more than 11 digits is shown as `[REDACTED]`. See [Batch lookups](/docs/batch-lookups/#card-number-redaction). Cut the card number to the first 8 digits in your application before you send it. Eight digits is enough for a specific match on most ranges, and it stays inside the 11-digit limit. ## How we store API keys - BINLookupAPI stores a hash of each key. The key itself is not stored. - The dashboard shows the first characters of each key only. - You can revoke a key at any time. The key stops immediately. BINLookupAPI cannot show a key after creation. See [Create a key](/docs/api-keys/#create-a-key). ## Request records BINLookupAPI stores a record of each API request. The record contains: - The API key that sent the request. The stored value is a hash, not the full key. - The BIN that you sent. - The HTTP status and the response time. - The IP address of the client. - The request headers, without the `Authorization` header and without other sensitive headers. - The request body, limited to 1 KB. - The response body, limited to 4 KB. BINLookupAPI does not store a full card number. The API rejects it before it stores the request. Records are kept while the account is open. This retention rule can change. A change is announced on the [changelog](/changelog/). The Usage page shows the request history. See the [dashboard](/docs/support/dashboard/#usage-page). ## Service providers | Provider | Purpose | |----------|---------| | Vercel | Application hosting. | | Stripe | Payments and invoices. BINLookupAPI does not store card details. | | Postmark | Transactional email. | | Pylon | Customer support. | | PostHog | Product analytics. | | Google Analytics | Website analytics. | BIN data comes from third-party vendors, banks, and the card networks. See [Data sources](/docs/support/data/#data-sources). BINLookupAPI hosts its database. Most of the data is in Europe. The [privacy policy](/privacy/) and the [terms](/terms/) are on this website. ## Delete an organisation You cannot delete an organisation or an account in the dashboard. Contact support to request a deletion. Before you send the request: 1. [Cancel the subscription](/docs/subscriptions/#cancel-a-subscription). 2. [Revoke the API keys](/docs/api-keys/#revoke-a-key). 3. Download the invoices that you need. See [Invoices](/docs/subscriptions/#invoices-and-payment-methods). Send an email to [support@binlookupapi.com](mailto:support@binlookupapi.com). Include the organisation name and the email address of an owner. BINLookupAPI confirms the deletion by email. ## Related pages - [API keys](/docs/api-keys/) - [Data](/docs/support/data/) - [Billing](/docs/subscriptions/) - [Privacy policy](/privacy/) - [Contact](/docs/support/contact/) --- --- title: "Troubleshooting Guide" description: "Causes and corrections for BIN lookup HTTP errors, quota errors, CSV upload failures, and billing problems." section: "Support" url: "https://binlookupapi.com/docs/support/troubleshooting/" markdown_url: "https://binlookupapi.com/docs/support/troubleshooting.md" --- # Troubleshooting Find the symptom below. The error codes themselves are specified in the [API reference](/docs/api-reference/#errors). ## HTTP 400 `BAD_REQUEST` means the API did not accept the body. | Cause | Correction | |-------|------------| | The body is not valid JSON. | Correct the JSON. Set `Content-Type: application/json`. | | The `number` field is missing. | Add `number` for one lookup, or `numbers` for a batch. | | The number has fewer than 6 digits or more than 11 digits. | Send 6 to 11 digits. Do not send a full card number. | | The number contains letters or spaces. | Send digits only. | | The body is larger than 1 KB. | Remove extra fields. | | `numbers` is empty or has more than 2,000 values. | Send 1 to 2,000 values. See [Batch lookups](/docs/batch-lookups/). | ## HTTP 401 `UNAUTHORIZED` means the API did not accept the API key. | Cause | Correction | |-------|------------| | The `Authorization` header is missing. | Add `Authorization: Bearer YOUR_API_KEY`. | | The header does not start with `Bearer`. | Add `Bearer` and one space before the key. | | The key has extra spaces or line breaks. | Remove them. | | The key is revoked or expired. | Check the status on API Keys. [Create a new key](/docs/api-keys/#create-a-key). | | The key is not complete. | Copy the full key from your secret store. The dashboard cannot show it again. | ## HTTP 403 | Error code | Cause | Correction | |------------|-------|------------| | `FEATURE_NOT_AVAILABLE` | The plan does not include the feature. The message names the plan. | Open `upgrade_url`, or [change the plan](/docs/subscriptions/#change-your-plan). | | `FORBIDDEN` | The key does not have permission for this endpoint. | [Create a new key](/docs/api-keys/#create-a-key). If the error continues, [contact support](/docs/support/contact/). | Batch lookup requires BLAPI-500KPM. The `meta` object requires BLAPI-150KPM or BLAPI-500KPM. A test-mode organisation can use both. ## HTTP 404 A 404 on every request is usually the URL, not the data. | Cause | Correction | |-------|------------| | The request went to the dashboard host. | Send it to `https://api.binlookupapi.com`. | | The path is wrong. | Use `/v1/bin` or `/v1/bins`. | | The method is GET. | Send POST. | A response with `"error": "NOT_FOUND"` is different. The URL is correct, and no record matches the BIN. See [When a BIN is not found](/docs/support/data/#when-a-bin-is-not-found). ## HTTP 429 `QUOTA_EXCEEDED` means the organisation used its daily quota. Requests work again after 00:00 UTC. | Cause | Explanation | |-------|-------------| | You expected a monthly limit. | The limit is per day. BLAPI-30KPM allows 1,000 requests each day. | | You expected a reset at local midnight. | The reset is at 00:00 UTC. | | You sent a batch. | Each BIN uses one unit. | | You use more than one API key. | All keys in the organisation share one quota. | | The subscription lapsed. | The organisation is on the free tier, with 10 lookups each day. | Read `X-Quota-Limit` and `X-Quota-Reset`. Check Remaining on the home page and the banners on Billing. See [Daily quota](/docs/subscriptions/#daily-quota). ## Missing fields - `meta` is missing on the free tier and on BLAPI-30KPM. See [The meta object](/docs/api-reference/#the-meta-object). - `null` is normal for `brand`, `category`, `currency`, and the issuer fields. The data source has no value. - Every field in `data` is always present. If a field is absent, [contact support](/docs/support/contact/) with the BIN and the request time. ## Batch page The Batch page processes files on BLAPI-500KPM only. On other plans it shows a preview. 1. Open Billing. 2. Change the plan to BLAPI-500KPM. See [Change your plan](/docs/subscriptions/#change-your-plan). 3. Open Batch again. An upgrade is active immediately. File rules are on the [Batch CSV](/docs/batch-csv/) page. ## CSV upload | Message | Correction | |---------|------------| | `Choose a CSV file to upload` | Select a file before you start. | | `The CSV file is empty` | Add at least one BIN. | | `The CSV file must be 1 MB or smaller` | Split the file. | | `CSV contains no data rows` | Add a data row. A header alone is not enough. | | `CSV has more than 2,000 data rows` | Use 2,000 data rows or fewer. | | `Daily quota exceeded` | Wait until 00:00 UTC, or remove rows. The page shows the required count and the remainder. | | `Lookup backend error` | Try again later. If it continues, contact support. | Save the file as CSV in UTF-8, with one BIN in one column. ## Payment not shown The dashboard usually shows the new plan within a few seconds after payment. 1. Wait one minute. 2. Refresh the Billing page. 3. Confirm the organisation. See [Switch organisation](/docs/support/dashboard/#switch-organisation). If the free tier is still shown, email [support@binlookupapi.com](mailto:support@binlookupapi.com). Include the organisation name, the email address used for payment, and the payment time. ## Missing emails Invitation emails and quota emails come from `noreply@binlookupapi.com`. Support emails come from `support@binlookupapi.com`. Add both addresses to your safe list. For an invitation: - Check the spam folder. - Ask an owner to check the address in Pending Invitations. - Ask the owner to cancel the invitation and send a new one. An invitation expires after 7 days. See [Invite a member](/docs/support/team/#invite-a-member). Quota emails go to owners and billing managers only. Check your role in Settings. See [Quota emails](/docs/subscriptions/#quota-emails). ## Related pages - [API reference](/docs/api-reference/) - [Billing](/docs/subscriptions/) - [API keys](/docs/api-keys/) - [Batch CSV](/docs/batch-csv/) - [Contact](/docs/support/contact/) --- --- title: "How to Contact Support" description: "How to contact BINLookupAPI support, what to include in a request, and the response time for each plan." section: "Support" url: "https://binlookupapi.com/docs/support/contact/" markdown_url: "https://binlookupapi.com/docs/support/contact.md" --- # Contact support ## Chat in the dashboard Sign in and select the chat icon. This is the fastest way to reach support. ## Email Send an email to [support@binlookupapi.com](mailto:support@binlookupapi.com). You can also use the [contact form](/contact/) on this website. ## Response times | Plan | Support level | Response time | |------|---------------|---------------| | Free tier, BLAPI-30KPM, BLAPI-150KPM | Email support | Within 1 business day. | | BLAPI-500KPM | Priority support | Within 8 hours, including hours outside the business day. | With priority support, the engineering team answers you directly. Plan details are on the [billing page](/docs/subscriptions/#plans). ## What to include - The organisation name. - The first characters of the API key. Do not send the full key. - The BIN that you sent. Do not send a full card number. - The time of the request, with the time zone. - The full error response. WARNING: Do not send a full API key or a full card number. ## Product updates Product updates are on the [changelog](/changelog/). ## Related pages - [Troubleshooting](/docs/support/troubleshooting/) - [Billing](/docs/subscriptions/) - [Quickstart](/docs/quickstart/) - [API reference](/docs/api-reference/) --- --- title: "BIN Lookup API Language Guides" description: "Language guides for the BIN Lookup API. Examples for curl, JavaScript, Python, PHP, Java, C#, and Go use the current POST /v1/bin endpoint." section: "Guides" url: "https://binlookupapi.com/docs/guides/" markdown_url: "https://binlookupapi.com/docs/guides.md" --- # Language guides Each guide calls the current API. The host is `https://api.binlookupapi.com`. The method is POST. Send the key as a bearer token. | Language | Guide | |----------|-------| | curl | [curl](/docs/guides/curl/) | | JavaScript (Node.js) | [JavaScript](/docs/guides/javascript/) | | Python | [Python](/docs/guides/python/) | | PHP | [PHP](/docs/guides/php/) | | Java | [Java](/docs/guides/java/) | | C# | [C#](/docs/guides/csharp/) | | Go | [Go](/docs/guides/go/) | ## Rules for every language - Create an API key first. See the [quickstart](/docs/quickstart/). - Store the key in an environment variable named `BINLOOKUP_API_KEY`. - Do not put the key in browser code or in a mobile application. - Send 6 to 11 digits. A JSON number or a string of digits is accepted. - Do not send a full card number. - Read `response.status` (or the HTTP status) before you read `data`. - Read `X-Quota-Remaining` and stop before it reaches zero. - Batch lookup is `POST /v1/bins` with a `numbers` array of 1 to 2,000 values. It requires BLAPI-500KPM, or a test-mode organisation. The field list, error codes, and quota headers are in the [API reference](/docs/api-reference/). ## Ruby ```ruby require "net/http" require "json" uri = URI("https://api.binlookupapi.com/v1/bin") request = Net::HTTP::Post.new(uri) request["Authorization"] = "Bearer #{ENV.fetch("BINLOOKUP_API_KEY")}" request["Content-Type"] = "application/json" request.body = { number: 42467101 }.to_json response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http| http.request(request) end payload = JSON.parse(response.body) if response.code == "200" puts payload["data"]["scheme"] else warn payload["error"] end ``` For a batch, send `numbers` to `POST /v1/bins`. See [Batch lookups](/docs/batch-lookups/). ## Related pages - [Quickstart](/docs/quickstart/) - [API reference](/docs/api-reference/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) --- --- title: "BIN Lookup API curl Guide" description: "Call the BIN Lookup API with curl. Send one BIN, read quota headers, and send a batch of up to 2,000 BINs." section: "Guides" url: "https://binlookupapi.com/docs/guides/curl/" markdown_url: "https://binlookupapi.com/docs/guides/curl.md" --- # BIN lookup with curl This page shows how to call the BIN Lookup API from a shell. You need curl and an API key. Create the key in the [quickstart](/docs/quickstart/). ## Store the key ```bash export BINLOOKUP_API_KEY="your_key_here" ``` Do not commit this value. Add the export to a private shell file, or use a secrets manager. ## Look up one BIN ```bash curl -sS -D - -o /tmp/bin-lookup.json \ -X POST "https://api.binlookupapi.com/v1/bin" \ -H "Authorization: Bearer $BINLOOKUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"number": 42467101}' ``` `-D -` prints the response headers, including the quota headers. The body is in `/tmp/bin-lookup.json`. A success body looks like this: ```json { "mode": "live", "data": { "bin": "42467101", "scheme": "visa", "funding": "debit", "brand": "VISA", "category": "CLASSIC", "country": { "code": "PL", "name": "POLAND" }, "issuer": { "name": "ING BANK SLASKI SA", "website": null, "phone": null }, "currency": "PLN", "prepaid": false, "commercial": false } } ``` Read one field with jq: ```bash jq -r '.data.scheme' /tmp/bin-lookup.json ``` ## Check the status code ```bash status=$(curl -sS -o /tmp/bin-lookup.json -w "%{http_code}" \ -X POST "https://api.binlookupapi.com/v1/bin" \ -H "Authorization: Bearer $BINLOOKUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"number": 42467101}') case "$status" in 200) jq '.data' /tmp/bin-lookup.json ;; 400) echo "The request body is not valid." ;; 401) echo "The API key is missing or not valid." ;; 403) echo "The plan or the key does not allow this request." ;; 404) echo "The BIN is not in the data." ;; 429) echo "The daily quota is used." ;; *) echo "The API returned HTTP $status." ;; esac ``` Error codes are in the [API reference](/docs/api-reference/#errors). HTTP 403 can be `FORBIDDEN` or `FEATURE_NOT_AVAILABLE`. Read the `error` field in the body. ## Read the quota ```bash curl -sS -D - -o /dev/null \ -X POST "https://api.binlookupapi.com/v1/bin" \ -H "Authorization: Bearer $BINLOOKUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"number": 42467101}' \ | grep -i '^X-Quota-' ``` There is no limit on requests per second. Stop when `X-Quota-Remaining` is low. See [Daily quota](/docs/subscriptions/#daily-quota). ## Look up many BINs Batch lookup requires BLAPI-500KPM, or a test-mode organisation. The array accepts 1 to 2,000 values. Each value uses one lookup. ```bash curl -sS -X POST "https://api.binlookupapi.com/v1/bins" \ -H "Authorization: Bearer $BINLOOKUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"numbers": [400062, "400597", 99999999]}' ``` The `results` array keeps your order. An item can contain `data` or an item error. One item error does not stop the other items. If the plan does not include batch lookup, the HTTP status is 403 and the error code is `FEATURE_NOT_AVAILABLE`. See [Batch lookups](/docs/batch-lookups/). ## Related pages - [API reference](/docs/api-reference/) - [JavaScript guide](/docs/guides/javascript/) - [Python guide](/docs/guides/python/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) --- --- title: "BIN Lookup API JavaScript Guide" description: "Call the BIN Lookup API from Node.js with fetch. Handle current error codes and send a batch lookup." section: "Guides" url: "https://binlookupapi.com/docs/guides/javascript/" markdown_url: "https://binlookupapi.com/docs/guides/javascript.md" --- # BIN lookup with JavaScript This page uses Node.js 18 or later. `fetch` is built in. Create an API key in the [quickstart](/docs/quickstart/). WARNING: Do not put the API key in browser code. Call the API from your server. ## Store the key ```bash export BINLOOKUP_API_KEY="your_key_here" ``` ## Look up one BIN ```javascript const apiKey = process.env.BINLOOKUP_API_KEY; const response = await fetch("https://api.binlookupapi.com/v1/bin", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ number: 42467101 }), }); const payload = await response.json(); if (response.status === 200) { console.log(payload.data.scheme, payload.data.issuer.name); console.log("Remaining:", response.headers.get("X-Quota-Remaining")); } else if (response.status === 401) { console.error("The API key is missing or not valid."); } else if (response.status === 403) { console.error(payload.error, payload.message); } else if (response.status === 404) { console.error("The BIN is not in the data."); } else if (response.status === 429) { console.error("The daily quota is used."); } else if (response.status === 400) { console.error(payload.message); } else { console.error(`The API returned HTTP ${response.status}.`); } ``` `payload.data` contains the fields in the [API reference](/docs/api-reference/#response-fields). On BLAPI-150KPM and above, `payload.meta.longer_bin_available` is also present. HTTP 403 is `FORBIDDEN` or `FEATURE_NOT_AVAILABLE`. Read `payload.error`. Some error bodies also contain `upgrade_url`. ## Look up many BINs `POST /v1/bins` accepts 1 to 2,000 values. It requires BLAPI-500KPM, or a test-mode organisation. Each value uses one lookup. ```javascript const response = await fetch("https://api.binlookupapi.com/v1/bins", { method: "POST", headers: { Authorization: `Bearer ${process.env.BINLOOKUP_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ numbers: [400062, "400597", 99999999] }), }); const payload = await response.json(); if (response.status === 403 && payload.error === "FEATURE_NOT_AVAILABLE") { console.error("Batch lookup needs the BLAPI-500KPM plan."); } else if (response.status === 200) { for (const item of payload.results) { if (item.data) { console.log(item.number, item.data.scheme); } else { console.log(item.number, item.error); } } } else if (response.status === 429) { console.error("Remaining:", response.headers.get("X-Quota-Remaining")); } ``` A 429 on a batch that does not fit uses no quota. `X-Quota-Remaining` is the real remainder. See [Batch lookups](/docs/batch-lookups/). ## Related pages - [curl guide](/docs/guides/curl/) - [Python guide](/docs/guides/python/) - [API reference](/docs/api-reference/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) --- --- title: "BIN Lookup API Python Guide" description: "Call the BIN Lookup API from Python with requests. Handle current error codes and send a batch lookup." section: "Guides" url: "https://binlookupapi.com/docs/guides/python/" markdown_url: "https://binlookupapi.com/docs/guides/python.md" --- # BIN lookup with Python This page uses Python 3 and the `requests` library. Create an API key in the [quickstart](/docs/quickstart/). ```bash pip install requests export BINLOOKUP_API_KEY="your_key_here" ``` ## Look up one BIN ```python import os import requests API_KEY = os.environ["BINLOOKUP_API_KEY"] URL = "https://api.binlookupapi.com/v1/bin" response = requests.post( URL, headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", }, json={"number": 42467101}, timeout=30, ) payload = response.json() if response.status_code == 200: data = payload["data"] print(data["scheme"], data["issuer"]["name"]) print("Remaining:", response.headers["X-Quota-Remaining"]) elif response.status_code == 401: raise SystemExit("The API key is missing or not valid.") elif response.status_code == 403: raise SystemExit(f"{payload.get('error')}: {payload.get('message')}") elif response.status_code == 404: raise SystemExit("The BIN is not in the data.") elif response.status_code == 429: raise SystemExit("The daily quota is used.") elif response.status_code == 400: raise SystemExit(payload.get("message", "The request is not valid.")) else: raise SystemExit(f"The API returned HTTP {response.status_code}.") ``` `data` contains the fields in the [API reference](/docs/api-reference/#response-fields). On BLAPI-150KPM and above, read `payload["meta"]["longer_bin_available"]`. On lower plans, `meta` is absent. HTTP 403 is `FORBIDDEN` or `FEATURE_NOT_AVAILABLE`. ## Look up many BINs `POST /v1/bins` accepts 1 to 2,000 values. It requires BLAPI-500KPM, or a test-mode organisation. Each value uses one lookup. ```python response = requests.post( "https://api.binlookupapi.com/v1/bins", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", }, json={"numbers": [400062, "400597", 99999999]}, timeout=60, ) payload = response.json() if response.status_code == 403 and payload.get("error") == "FEATURE_NOT_AVAILABLE": raise SystemExit("Batch lookup needs the BLAPI-500KPM plan.") response.raise_for_status() for item in payload["results"]: if "data" in item: print(item["number"], item["data"]["scheme"]) else: print(item["number"], item["error"]) ``` If the batch is larger than the remaining quota, the status is 429 and no quota is used. Read `X-Quota-Remaining` and split the list. See [Batch lookups](/docs/batch-lookups/). ## Related pages - [JavaScript guide](/docs/guides/javascript/) - [PHP guide](/docs/guides/php/) - [API reference](/docs/api-reference/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) --- --- title: "BIN Lookup API PHP Guide" description: "Call the BIN Lookup API from PHP with cURL. Handle current error codes and send a batch lookup." section: "Guides" url: "https://binlookupapi.com/docs/guides/php/" markdown_url: "https://binlookupapi.com/docs/guides/php.md" --- # BIN lookup with PHP This page uses PHP with the curl extension. Create an API key in the [quickstart](/docs/quickstart/). Put the key in the environment variable `BINLOOKUP_API_KEY`. ## Look up one BIN ```php true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . $apiKey, "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode(["number" => 42467101]), ]); $raw = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE); curl_close($ch); $headers = substr($raw, 0, $headerSize); $body = json_decode(substr($raw, $headerSize), true); if ($status === 200) { echo $body["data"]["scheme"], "\n"; } elseif ($status === 401) { fwrite(STDERR, "The API key is missing or not valid.\n"); } elseif ($status === 403) { fwrite(STDERR, $body["error"] . ": " . $body["message"] . "\n"); } elseif ($status === 404) { fwrite(STDERR, "The BIN is not in the data.\n"); } elseif ($status === 429) { fwrite(STDERR, "The daily quota is used.\n"); } elseif ($status === 400) { fwrite(STDERR, $body["message"] . "\n"); } else { fwrite(STDERR, "The API returned HTTP {$status}.\n"); } ``` `data` contains the fields in the [API reference](/docs/api-reference/#response-fields). On BLAPI-150KPM and above, read `$body["meta"]["longer_bin_available"]`. The quota headers are in `$headers`. There is no limit on requests per second. ## Look up many BINs `POST /v1/bins` accepts 1 to 2,000 values. It requires BLAPI-500KPM, or a test-mode organisation. ```php true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("BINLOOKUP_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "numbers" => [400062, "400597", 99999999], ]), ]); $body = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status === 403 && ($body["error"] ?? "") === "FEATURE_NOT_AVAILABLE") { fwrite(STDERR, "Batch lookup needs the BLAPI-500KPM plan.\n"); exit(1); } foreach ($body["results"] as $item) { if (isset($item["data"])) { echo $item["number"], " ", $item["data"]["scheme"], "\n"; } else { echo $item["number"], " ", $item["error"], "\n"; } } ``` See [Batch lookups](/docs/batch-lookups/). One item error does not stop the other items. ## Related pages - [Python guide](/docs/guides/python/) - [Java guide](/docs/guides/java/) - [API reference](/docs/api-reference/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) --- --- title: "BIN Lookup API Java Guide" description: "Call the BIN Lookup API from Java 11 or later with HttpClient. Handle current error codes and send a batch lookup." section: "Guides" url: "https://binlookupapi.com/docs/guides/java/" markdown_url: "https://binlookupapi.com/docs/guides/java.md" --- # BIN lookup with Java This page uses Java 11 or later and `java.net.http.HttpClient`. Create an API key in the [quickstart](/docs/quickstart/). Read it from the environment variable `BINLOOKUP_API_KEY`. ## Look up one BIN ```java public class BinLookup { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newHttpClient(); String apiKey = System.getenv("BINLOOKUP_API_KEY"); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.binlookupapi.com/v1/bin")) .header("Authorization", "Bearer " + apiKey) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString("{\"number\":42467101}")) .build(); HttpResponse response = client.send( request, HttpResponse.BodyHandlers.ofString() ); int status = response.statusCode(); if (status == 200) { System.out.println(response.body()); System.out.println(response.headers().firstValue("X-Quota-Remaining").orElse("")); } else if (status == 401) { System.err.println("The API key is missing or not valid."); } else if (status == 403) { System.err.println(response.body()); } else if (status == 404) { System.err.println("The BIN is not in the data."); } else if (status == 429) { System.err.println("The daily quota is used."); } else if (status == 400) { System.err.println(response.body()); } else { System.err.println("The API returned HTTP " + status); } } } ``` Parse `data` with your JSON library. The fields are in the [API reference](/docs/api-reference/#response-fields). On BLAPI-150KPM and above, the body also contains `meta.longer_bin_available`. HTTP 403 is `FORBIDDEN` or `FEATURE_NOT_AVAILABLE`. Read the `error` field. ## Look up many BINs `POST /v1/bins` accepts 1 to 2,000 values. It requires BLAPI-500KPM, or a test-mode organisation. Each value uses one lookup. ```java HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.binlookupapi.com/v1/bins")) .header("Authorization", "Bearer " + System.getenv("BINLOOKUP_API_KEY")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString( "{\"numbers\":[400062,\"400597\",99999999]}" )) .build(); HttpResponse response = client.send( request, HttpResponse.BodyHandlers.ofString() ); if (response.statusCode() == 403 && response.body().contains("FEATURE_NOT_AVAILABLE")) { System.err.println("Batch lookup needs the BLAPI-500KPM plan."); } else if (response.statusCode() == 200) { System.out.println(response.body()); } ``` The `results` array keeps your order. See [Batch lookups](/docs/batch-lookups/). If the batch does not fit in the remaining quota, the status is 429 and no quota is used. ## Related pages - [PHP guide](/docs/guides/php/) - [C# guide](/docs/guides/csharp/) - [API reference](/docs/api-reference/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) --- --- title: "BIN Lookup API C# Guide" description: "Call the BIN Lookup API from C# with HttpClient. Handle current error codes and send a batch lookup." section: "Guides" url: "https://binlookupapi.com/docs/guides/csharp/" markdown_url: "https://binlookupapi.com/docs/guides/csharp.md" --- # BIN lookup with C# This page uses .NET and `HttpClient`. Create an API key in the [quickstart](/docs/quickstart/). Read it from the environment variable `BINLOOKUP_API_KEY`. ## Look up one BIN ```csharp using System.Net.Http.Headers; using System.Text; using System.Text.Json; using var client = new HttpClient(); var apiKey = Environment.GetEnvironmentVariable("BINLOOKUP_API_KEY"); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey); var body = new StringContent( JsonSerializer.Serialize(new { number = 42467101 }), Encoding.UTF8, "application/json" ); var response = await client.PostAsync("https://api.binlookupapi.com/v1/bin", body); var payload = await response.Content.ReadAsStringAsync(); switch ((int)response.StatusCode) { case 200: Console.WriteLine(payload); Console.WriteLine(response.Headers.GetValues("X-Quota-Remaining").FirstOrDefault()); break; case 401: Console.Error.WriteLine("The API key is missing or not valid."); break; case 403: Console.Error.WriteLine(payload); break; case 404: Console.Error.WriteLine("The BIN is not in the data."); break; case 429: Console.Error.WriteLine("The daily quota is used."); break; case 400: Console.Error.WriteLine(payload); break; default: Console.Error.WriteLine($"The API returned HTTP {(int)response.StatusCode}."); break; } ``` Parse `data` from the JSON. The fields are in the [API reference](/docs/api-reference/#response-fields). On BLAPI-150KPM and above, the body also contains `meta.longer_bin_available`. HTTP 403 is `FORBIDDEN` or `FEATURE_NOT_AVAILABLE`. Read the `error` property. ## Look up many BINs `POST /v1/bins` accepts 1 to 2,000 values. It requires BLAPI-500KPM, or a test-mode organisation. Each value uses one lookup. ```csharp var body = new StringContent( JsonSerializer.Serialize(new { numbers = new object[] { 400062, "400597", 99999999 } }), Encoding.UTF8, "application/json" ); var response = await client.PostAsync("https://api.binlookupapi.com/v1/bins", body); var payload = await response.Content.ReadAsStringAsync(); if ((int)response.StatusCode == 403 && payload.Contains("FEATURE_NOT_AVAILABLE")) { Console.Error.WriteLine("Batch lookup needs the BLAPI-500KPM plan."); } else if (response.IsSuccessStatusCode) { Console.WriteLine(payload); } ``` The `results` array keeps your order. See [Batch lookups](/docs/batch-lookups/). A batch that does not fit in the remaining quota returns 429 and uses no quota. ## Related pages - [Java guide](/docs/guides/java/) - [Go guide](/docs/guides/go/) - [API reference](/docs/api-reference/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) --- --- title: "BIN Lookup API Go Guide" description: "Call the BIN Lookup API from Go with net/http. Handle current error codes and send a batch lookup." section: "Guides" url: "https://binlookupapi.com/docs/guides/go/" markdown_url: "https://binlookupapi.com/docs/guides/go.md" --- # BIN lookup with Go This page uses the Go standard library. Create an API key in the [quickstart](/docs/quickstart/). Read it from the environment variable `BINLOOKUP_API_KEY`. ## Look up one BIN ```go package main import ( "bytes" "fmt" "io" "net/http" "os" "time" ) func main() { body := bytes.NewBufferString(`{"number":42467101}`) req, err := http.NewRequest(http.MethodPost, "https://api.binlookupapi.com/v1/bin", body) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer "+os.Getenv("BINLOOKUP_API_KEY")) req.Header.Set("Content-Type", "application/json") client := &http.Client{Timeout: 30 * time.Second} resp, err := client.Do(req) if err != nil { panic(err) } defer resp.Body.Close() payload, _ := io.ReadAll(resp.Body) switch resp.StatusCode { case 200: fmt.Println(string(payload)) fmt.Println(resp.Header.Get("X-Quota-Remaining")) case 401: fmt.Fprintln(os.Stderr, "The API key is missing or not valid.") case 403: fmt.Fprintln(os.Stderr, string(payload)) case 404: fmt.Fprintln(os.Stderr, "The BIN is not in the data.") case 429: fmt.Fprintln(os.Stderr, "The daily quota is used.") case 400: fmt.Fprintln(os.Stderr, string(payload)) default: fmt.Fprintf(os.Stderr, "The API returned HTTP %d.\n", resp.StatusCode) } } ``` The success JSON has `mode` and `data`. The fields are in the [API reference](/docs/api-reference/#response-fields). On BLAPI-150KPM and above, the body also contains `meta.longer_bin_available`. HTTP 403 is `FORBIDDEN` or `FEATURE_NOT_AVAILABLE`. Read the `error` field. ## Look up many BINs `POST /v1/bins` accepts 1 to 2,000 values. It requires BLAPI-500KPM, or a test-mode organisation. Each value uses one lookup. ```go client := &http.Client{Timeout: 60 * time.Second} body := bytes.NewBufferString(`{"numbers":[400062,"400597",99999999]}`) req, err := http.NewRequest(http.MethodPost, "https://api.binlookupapi.com/v1/bins", body) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer "+os.Getenv("BINLOOKUP_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := client.Do(req) if err != nil { panic(err) } defer resp.Body.Close() payload, _ := io.ReadAll(resp.Body) if resp.StatusCode == 403 && bytes.Contains(payload, []byte("FEATURE_NOT_AVAILABLE")) { fmt.Fprintln(os.Stderr, "Batch lookup needs the BLAPI-500KPM plan.") return } if resp.StatusCode == 200 { fmt.Println(string(payload)) } ``` The `results` array keeps your order. See [Batch lookups](/docs/batch-lookups/). A batch that does not fit in the remaining quota returns 429 and uses no quota. ## Related pages - [C# guide](/docs/guides/csharp/) - [curl guide](/docs/guides/curl/) - [API reference](/docs/api-reference/) - [API keys](/docs/api-keys/) - [Billing](/docs/subscriptions/) ---