BIN lookup API examples that keep the key private

Quick start

curl --request GET \
  'https://bintools.io/api/v1/lookup?bin=498542' \
  --header 'X-API-Key: bt_YOUR_API_KEY'

The placeholder is intentional. Replace it only in your local secret store or deployment environment. The service also accepts Authorization: Bearer ….

Node.js server example

This example is suitable for a server route, worker or background job. It validates the input, reads the key from the environment and distinguishes rate limiting from other failures.

const digits = String(input).replace(/\D/g, "");
if (digits.length < 6) throw new Error("BIN needs at least 6 digits");

const response = await fetch(
  `https://bintools.io/api/v1/lookup?bin=${digits.slice(0, 8)}`,
  { headers: { "X-API-Key": process.env.BINTOOLS_API_KEY } }
);

if (response.status === 429) {
  throw new Error("BINtools limit reached; retry later");
}
if (!response.ok) {
  const problem = await response.json();
  throw new Error(problem.error ?? `HTTP ${response.status}`);
}

const binData = await response.json();

Python example

import os
import re
import requests

digits = re.sub(r"\D", "", user_input)
if len(digits) < 6:
    raise ValueError("BIN needs at least 6 digits")

response = requests.get(
    "https://bintools.io/api/v1/lookup",
    params={"bin": digits[:8]},
    headers={"X-API-Key": os.environ["BINTOOLS_API_KEY"]},
    timeout=10,
)
response.raise_for_status()
bin_data = response.json()

In this example only the BIN value is a query parameter. The API key remains in a header. Set a short timeout and catch requests.HTTPError so a metadata lookup cannot stall your main transaction flow.

Response fields

Six-digit lookup granularity

The public BINtools reference currently contains 375,518 distinct six-digit records. The v1 lookup normalizes the input and matches the first six digits against that source. A client can preserve up to eight input digits for its own workflow, but it must not present the result as verified eight-digit IIN classification.

Two cards can share the same first six digits while belonging to different eight-digit sub-ranges. That matters for routing, product classification, fraud analytics and reporting. Use a network-authorized or processor source when eight-digit precision is required.

Error handling

The authenticated status endpoint returns the active plan, daily and monthly usage limits, usage counts and the configured BIN digit setting. Use it for operational monitoring—not on every lookup.

Caching and logging

• Cache successful reference results by the matched six-digit prefix, not by the full PAN.
• Keep a source timestamp and refresh on a controlled schedule because issuer assignments change.
• Do not cache 401, 403 or 429 responses as permanent lookup results.
• Never log the API key or a full card number. A BIN metadata lookup does not need the PAN.
• Use request timeouts and circuit breaking so a reference lookup cannot block payment processing.
• Record the response status, latency and match granularity for diagnostics without storing sensitive input.

Versioned API vs legacy browser endpoints

The website still uses several anonymous /api/*.php endpoints for interactive tools. They have per-IP controls and anti-abuse checks and are not the stable integration surface for a backend product.

New integrations should use /api/v1/lookup with a named key. This gives account-level limits, usage tracking, key activation controls and a separate status endpoint.

Frequently asked questions

Start with one controlled integration

Create a separate key for each environment, keep production credentials out of developer laptops where possible and begin with a single server-side lookup path. Measure errors and latency before adding BIN metadata to a wider workflow.