API Reference Documentation

Comprehensive guide to the BIN Lookup API endpoints, response fields, and their possible values.

1. API Overview

The BIN Lookup API provides instant Bank Identification Number (BIN) lookups with optional IP geolocation data for enhanced security and fraud detection.

Authentication

All API requests require a RapidAPI key. You can subscribe and get your API key from the RapidAPI BIN Lookup & IP Intelligence API page.

Include your RapidAPI key in the X-RapidAPI-Key header.

X-RapidAPI-Key: your_rapidapi_key

Rate Limiting

Rate limits apply and vary by subscription tier. Please refer to your subscription details for specific limits.

Response Format

All responses are returned in JSON format with UTF-8 encoding.

2. Endpoints

`GET /api/v1/lookup`

Retrieves Bank Identification Number (BIN) information with optional IP geolocation data.

Query Parameters

binstring

Bank Identification Number. Must be 6-11 digits. Spaces and dashes are automatically stripped.

Example:

"424242"

ipstring (optional)

IP address (IPv4 or IPv6) for geolocation lookup and security analysis. When provided, the response includes IP location data and security risk assessment.

Example:

"8.8.8.8"

Headers

X-RapidAPI-Keystring

RapidAPI key for authentication. Required for all API requests. Get your key from the RapidAPI listing.

Example:

"your_rapidapi_key"

3. Core Response Fields

binstring

The BIN number (6-11 digits) that was queried

Example:

"424242"

validboolean

Whether the BIN is valid and exists in the database

Possible Values:

truefalse

Example:

true

schemestring | null

Card scheme/brand (payment network)

Possible Values:

VISAMASTERCARDAMEXDISCOVERDINERSJCBUNIONPAY

Example:

"VISA"

typestring | null

Card type classification

Possible Values:

CREDITDEBIT

Example:

"CREDIT"

card_categorystring | null

Card category/tier classification. Common values include CLASSIC, GOLD, PLATINUM, BUSINESS, CORPORATE, PREPAID, STANDARD. Other values may exist from the data source.

Possible Values:

CLASSICGOLDPLATINUMBUSINESSCORPORATEPREPAIDSTANDARD

Example:

"CLASSIC"

currency_codestring | null

ISO 4217 currency code for the card's country

Example:

"USD"

4. Issuer Object

Information about the card issuer (bank or financial institution).

issuer.namestring | null

Name of the issuing bank or financial institution

Example:

"CHASE BANK USA, N.A."

issuer.country_codestring | null

ISO 3166-1 alpha-2 country code of the issuer

Example:

"US"

issuer.phonestring | null

Contact phone number for the issuer

Example:

"1-800-935-9935"

issuer.websitestring | null

Website URL of the issuer

Example:

"https://www.chase.com"

5. Attributes Object

Card attributes indicating card characteristics.

attributes.is_commercialboolean

Whether the card is a commercial/business card

Possible Values:

truefalse

Example:

false

attributes.is_prepaidboolean

Whether the card is a prepaid card

Possible Values:

truefalse

Example:

false

attributes.is_reloadableboolean

Whether the prepaid card is reloadable. Only meaningful if is_prepaid is true.

Possible Values:

truefalse

Example:

false

6. IP Location Object

Conditional Field: This object is only included when the ip query parameter is provided and IP lookup succeeds.

IP geolocation data from the provided IP address.

ip_location.countrystring | null

Country name or code from IP geolocation

Example:

"US"

ip_location.regionstring | null

Region/state name from IP geolocation

Example:

"California"

ip_location.citystring | null

City name from IP geolocation

Example:

"Mountain View"

ip_location.organizationstring | null

Organization/ISP name associated with the IP

Example:

"Google LLC"

ip_location.hostnamestring | null

Reverse DNS hostname of the IP address

Example:

"dns.google"

ip_location.timezonestring | null

Timezone associated with the IP location

Example:

"America/Los_Angeles"

ip_location.coordsobject | null

Geographic coordinates (latitude/longitude). Null if coordinates are not available.

Example:

null

ip_location.coords.latitudenumber

Latitude coordinate

37.4056

ip_location.coords.longitudenumber

Longitude coordinate

-122.0775

ip_location.currencystring | null

ISO 4217 currency code for the IP's country

Example:

"USD"

7. Intelligence Object

Conditional Field: This object is only included for valid BINs. Invalid BINs will not have an intelligence object to prevent false positives.

Business intelligence layer with routing, subscription, and security recommendations.

Routing Intelligence

intelligence.routing.tierenum

Card tier classification for payment routing

Possible Values:

PREMIUM_BUSINESSSTANDARD_CONSUMER

Example:

"STANDARD_CONSUMER"

intelligence.routing.interchange_profileenum

Expected interchange fee profile

Possible Values:

LOWMEDIUMHIGH

Example:

"MEDIUM"

intelligence.routing.recommendationenum

Routing recommendation for payment processing optimization

Possible Values:

ROUTE_TO_PREMIUMROUTE_TO_LOWER_COSTROUTE_STANDARD

Example:

"ROUTE_STANDARD"

Subscription Intelligence

intelligence.subscription.healthenum

Risk assessment for recurring payments

Possible Values:

RISKSAFEMEDIUM

Example:

"SAFE"

intelligence.subscription.recommendationenum

Recommendation for handling recurring payments

Possible Values:

BLOCK_RECURRINGACCEPTMONITOR_RECURRING

Example:

"ACCEPT"

intelligence.subscription.is_recurring_compatibleboolean

Whether the card is compatible with recurring payment processing

Possible Values:

truefalse

Example:

true

Security Intelligence

Conditional Field: This object is only included when IP is provided and both IP and card country codes are available.

intelligence.security.ip_countrystring | null

Country code from IP geolocation

Example:

"US"

intelligence.security.card_countrystring | null

Country code from BIN data

Example:

"US"

intelligence.security.matchboolean

Whether the IP country matches the card country

Possible Values:

truefalse

Example:

true

intelligence.security.risk_levelenum

Security risk level based on country matching

Possible Values:

HIGHSAFE

Example:

"SAFE"

8. Meta Object

Request metadata.

meta.request_idstring (UUID)

Unique request identifier (UUID format)

Example:

"550e8400-e29b-41d4-a716-446655440000"

9. Example Responses

Valid BIN with IP (Full Response)

Complete response when a valid BIN is queried with an IP address parameter.

{
  "bin": "424242",
  "valid": true,
  "scheme": "VISA",
  "type": "CREDIT",
  "card_category": null,
  "currency_code": "USD",
  "issuer": {
    "name": "CHASE BANK USA, N.A.",
    "country_code": "US",
    "phone": "1-800-935-9935",
    "website": "https://www.chase.com"
  },
  "attributes": {
    "is_commercial": false,
    "is_prepaid": false,
    "is_reloadable": false
  },
  "ip_location": {
    "country": "US",
    "region": "California",
    "city": "Mountain View",
    "organization": "Google LLC",
    "hostname": "dns.google",
    "timezone": "America/Los_Angeles",
    "coords": {
      "latitude": 37.4056,
      "longitude": -122.0775
    },
    "currency": "USD"
  },
  "intelligence": {
    "routing": {
      "tier": "STANDARD_CONSUMER",
      "interchange_profile": "MEDIUM",
      "recommendation": "ROUTE_STANDARD"
    },
    "subscription": {
      "health": "SAFE",
      "recommendation": "ACCEPT",
      "is_recurring_compatible": true
    },
    "security": {
      "ip_country": "US",
      "card_country": "US",
      "match": true,
      "risk_level": "SAFE"
    }
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Valid BIN without IP

Response when a valid BIN is queried without an IP address. Note the absence of ip_location and intelligence.security fields.

{
  "bin": "424242",
  "valid": true,
  "scheme": "VISA",
  "type": "CREDIT",
  "card_category": null,
  "currency_code": "USD",
  "issuer": {
    "name": "CHASE BANK USA, N.A.",
    "country_code": "US",
    "phone": "1-800-935-9935",
    "website": "https://www.chase.com"
  },
  "attributes": {
    "is_commercial": false,
    "is_prepaid": false,
    "is_reloadable": false
  },
  "intelligence": {
    "routing": {
      "tier": "STANDARD_CONSUMER",
      "interchange_profile": "MEDIUM",
      "recommendation": "ROUTE_STANDARD"
    },
    "subscription": {
      "health": "SAFE",
      "recommendation": "ACCEPT",
      "is_recurring_compatible": true
    }
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440001"
  }
}

Invalid BIN

Response when an invalid BIN is queried. Note that all data fields are null and the intelligence object is completely omitted.

{
  "bin": "12312312",
  "valid": false,
  "scheme": null,
  "type": null,
  "card_category": null,
  "currency_code": null,
  "issuer": {
    "name": null,
    "country_code": null,
    "phone": null,
    "website": null
  },
  "attributes": {
    "is_commercial": false,
    "is_prepaid": false,
    "is_reloadable": false
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440002"
  }
}

10. Error Responses

All error responses follow a consistent structure with an error field containing the error message.

400 Bad Request

Invalid input parameters.

Invalid BIN format:

{"error": "Invalid BIN format. Provide 6-11 digits (spaces/dashes are allowed)"}

Invalid IP format:

{"error": "Invalid IP address format. Provide a valid IPv4 or IPv6 address"}

401 Unauthorized

Missing or invalid authentication.

Missing authentication header:

{"error": "Missing X-RapidAPI-Key header"}

Invalid RapidAPI key:

{"error": "Invalid API key"}

404 Not Found

BIN not found in the database.

{"error": "BIN not found"}

500 Internal Server Error

Server error or external service failure.

{"error": "Failed to lookup BIN. Please try again later."}

11. Conditional Fields Guide

ip_location Object

When it appears: Only included when the ip query parameter is provided and IP lookup succeeds.

When it's omitted: When no IP parameter is provided, or when IP lookup fails (graceful degradation).

intelligence Object

When it appears: Only included for valid BINs. This prevents false positives where invalid cards would be marked as "SAFE".

When it's omitted: When the BIN is invalid (valid: false). All intelligence recommendations are omitted to prevent dangerous defaults.

intelligence.security Object

When it appears: Only included when:

IP parameter is provided
IP lookup succeeds
Both IP country code and card country code are available

When it's omitted: When any of the above conditions are not met, even if the intelligence object is present.

Graceful Degradation

The API implements graceful degradation: if IP lookup fails but BIN lookup succeeds, the API returns a partial success response with BIN data only. The ip_location and intelligence.security fields are simply omitted, and the response still contains all other available data.

12. Field Value Reference

Enum Values

Field	Values	Description
scheme	VISAMASTERCARDAMEXDISCOVERDINERSJCBUNIONPAY	Card payment network/brand (common values; others may exist)
type	CREDITDEBIT	Card type classification
card_category	CLASSICGOLDPLATINUMBUSINESSCORPORATEPREPAIDSTANDARD	Card category/tier (common values; others may exist)
routing.tier	PREMIUM_BUSINESSSTANDARD_CONSUMER	Card tier for payment routing
routing.interchange_profile	LOWMEDIUMHIGH	Expected interchange fee level
routing.recommendation	ROUTE_TO_PREMIUMROUTE_TO_LOWER_COSTROUTE_STANDARD	Payment routing recommendation
subscription.health	RISKSAFEMEDIUM	Recurring payment risk assessment
subscription.recommendation	BLOCK_RECURRINGACCEPTMONITOR_RECURRING	Recurring payment handling recommendation
security.risk_level	HIGHSAFE	Security risk based on country matching

Boolean Fields

valid

true: BIN exists in database and is recognized
false: BIN not found or invalid

attributes.is_commercial

true: Business/commercial card
false: Consumer/personal card

attributes.is_prepaid

true: Prepaid card
false: Regular credit/debit card

attributes.is_reloadable

true: Prepaid card can be reloaded with funds
false: Prepaid card is single-use or non-reloadable

intelligence.subscription.is_recurring_compatible

true: Card supports recurring payments
false: Card should not be used for recurring payments

intelligence.security.match

true: IP country matches card country (lower risk)
false: IP country differs from card country (higher risk)

Null Values

Many fields can be null when data is not available. This is common for:

Invalid BINs (all data fields will be null)
Missing issuer information (issuer fields may be null)
Unavailable IP geolocation data (ip_location fields may be null)
Unknown card categories or schemes

Always check for null values before using field data in your application logic.

API Reference Documentation

Table of Contents

1. API Overview

Authentication

Rate Limiting

Response Format

2. Endpoints

GET /api/v1/lookup

Query Parameters

Headers

3. Core Response Fields

4. Issuer Object

5. Attributes Object

6. IP Location Object

7. Intelligence Object

Routing Intelligence

Subscription Intelligence

Security Intelligence

8. Meta Object

9. Example Responses

Valid BIN with IP (Full Response)

Valid BIN without IP

Invalid BIN

10. Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

11. Conditional Fields Guide

ip_location Object

intelligence Object

intelligence.security Object

Graceful Degradation

12. Field Value Reference

Enum Values

Boolean Fields

Null Values

`GET /api/v1/lookup`