---
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/)