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.

Store the key

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

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:

{
  "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:

jq -r '.data.scheme' /tmp/bin-lookup.json

Check the status code

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. HTTP 403 can be FORBIDDEN or FEATURE_NOT_AVAILABLE. Read the error field in the body.

Read the quota

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.

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.

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.