{ "openapi": "3.0.0", "info": { "title": "BIN Lookup API", "version": "1.0.0", "description": "API for looking up Bank Identification Number (BIN) data to retrieve card metadata including scheme, funding type, issuer information, and more." }, "servers": [ { "url": "https://api.binlookupapi.com", "description": "Production server" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key authentication. Include your API key in the Authorization header as 'Bearer '." } }, "schemas": { "BinLookupRequestSchema": { "type": "object", "properties": { "number": { "oneOf": [ { "type": "integer", "minimum": 100000, "maximum": 99999999999 }, { "type": "string", "pattern": "^(?=\\d{1,11}$)0*[1-9]\\d{5,10}$" } ], "description": "Bank Identification Number as an integer (6-11 digits). Digit strings are accepted for compatibility and coerced to the same integer value; leading zeroes are not preserved." } }, "required": [ "number" ] }, "BinLookupSuccessResponse": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/ModeSchema" }, "data": { "$ref": "#/components/schemas/BinDataSchema" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/BinLookupMetaSchema" } ] } }, "required": [ "mode", "data" ] }, "BinBatchLookupRequestSchema": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "oneOf": [ { "type": "integer", "minimum": 100000, "maximum": 99999999999 }, { "type": "string", "pattern": "^(?=\\d{1,11}$)0*[1-9]\\d{5,10}$" } ] }, "minItems": 1, "maxItems": 2000 } }, "required": [ "numbers" ], "description": "A batch of 1 to 2,000 BIN values following the same per-item rules as a single lookup. Every submitted entry counts against the daily quota." }, "BinBatchLookupSuccessResponse": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/ModeSchema" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BinBatchItemResultSchema" }, "description": "One result per submitted number, in the same order" } }, "required": [ "mode", "results" ] }, "ModeSchema": { "type": "string", "enum": [ "test", "live" ], "description": "Organisation mode - test returns mock data, live returns real data" }, "CardSchemeSchema": { "type": "string", "enum": [ "visa", "mastercard", "amex", "discover", "jcb", "unionpay", "diners", "unknown" ], "description": "Card network/scheme" }, "CardFundingSchema": { "type": "string", "enum": [ "credit", "debit", "prepaid", "unknown" ], "description": "Card funding type: credit, debit, prepaid, or unknown" }, "BinDataSchema": { "type": "object", "properties": { "bin": { "type": "string", "description": "The BIN that was looked up" }, "scheme": { "$ref": "#/components/schemas/CardSchemeSchema" }, "funding": { "$ref": "#/components/schemas/CardFundingSchema" }, "brand": { "type": "string", "nullable": true, "description": "Card brand or product name" }, "category": { "type": "string", "nullable": true, "description": "Card category (e.g., CLASSIC, GOLD)" }, "country": { "type": "object", "properties": { "code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "name": { "type": "string", "description": "Country name" } }, "required": [ "code", "name" ] }, "issuer": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Issuing bank name" }, "website": { "type": "string", "nullable": true, "description": "Issuing bank website" }, "phone": { "type": "string", "nullable": true, "description": "Issuing bank phone number" } } }, "currency": { "type": "string", "nullable": true, "description": "ISO 4217 currency code" }, "prepaid": { "type": "boolean", "description": "Whether the card is prepaid" }, "commercial": { "type": "boolean", "description": "Whether the card is a commercial/business card" } }, "required": [ "bin", "scheme", "funding", "country", "issuer", "prepaid", "commercial" ] }, "BinLookupMetaSchema": { "type": "object", "properties": { "longer_bin_available": { "type": "boolean", "description": "Whether the dataset holds records for longer BINs starting with the queried BIN. When true, resubmitting with more digits of the card number may return more specific data." } }, "required": [ "longer_bin_available" ], "description": "Lookup metadata. Only present when the organisation's plan includes the meta feature; omitted otherwise." }, "BinBatchItemSuccessSchema": { "type": "object", "properties": { "number": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "The submitted value, echoed back" }, "data": { "$ref": "#/components/schemas/BinDataSchema" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/BinLookupMetaSchema" } ] } }, "required": [ "number", "data" ] }, "BinBatchItemErrorSchema": { "type": "object", "properties": { "number": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "The submitted value, echoed back; values longer than 11 digits are returned as \"[REDACTED]\"" }, "error": { "type": "string", "enum": [ "BAD_REQUEST", "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "number", "error", "message" ] }, "BinBatchItemResultSchema": { "oneOf": [ { "$ref": "#/components/schemas/BinBatchItemSuccessSchema" }, { "$ref": "#/components/schemas/BinBatchItemErrorSchema" } ] }, "BinLookupErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_NOT_AVAILABLE", "NOT_FOUND", "QUOTA_EXCEEDED", "SERVICE_ERROR" ], "description": "Error code" }, "message": { "type": "string", "description": "Human-readable error description" }, "upgrade_url": { "type": "string", "nullable": true, "description": "Link to the organisation's billing page. Present when the free-tier daily limit is exceeded." } }, "required": [ "error", "message" ] } }, "responses": { "400": { "description": "Bad Request - Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "400" }, "message": { "type": "string", "example": "number must be an integer between 4 and 11 digits" } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "401" }, "message": { "type": "string", "example": "Invalid or missing API key" } } } } } }, "402": { "description": "Payment Required - Active subscription required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "402" }, "message": { "type": "string", "example": "Active subscription required" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "403" }, "message": { "type": "string", "example": "API key does not have required scope" } } } } } }, "404": { "description": "Not Found - BIN not found in database", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "404" }, "message": { "type": "string", "example": "BIN not found" } } } } } }, "429": { "description": "Too Many Requests - Daily quota exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "429" }, "message": { "type": "string", "example": "Daily request quota exceeded" } } } } } }, "502": { "description": "Bad Gateway - Upstream service error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "502" }, "message": { "type": "string", "example": "An error occurred" } } } } } } } }, "paths": { "/v1/bin": { "post": { "operationId": "post-v1-bin", "summary": "Look up BIN data", "description": "Retrieve card metadata from a Bank Identification Number (BIN) - the first 6 to 11 digits of a payment card number. The canonical request value is an integer; digit strings are accepted for compatibility and coerced to the same integer value. On plans that include the meta feature, responses also carry a meta object with longer_bin_available, which signals that the dataset has more specific records for longer BINs sharing the submitted prefix; on other plans the field is omitted.", "tags": [ "V1" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } }, "502": { "description": "HTTP 502", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } } } } }, "/v1/bins": { "post": { "operationId": "post-v1-bins", "summary": "Batch BIN lookup", "description": "Look up card metadata for up to 2,000 BINs in one request. Available on plans that include batch lookups; test-mode organisations always have access and receive mock data (note the test-mode daily limit of 500 units caps test batches). Results are returned in submission order, one entry per submitted value; unrecognized values yield a per-item NOT_FOUND and invalid values a per-item BAD_REQUEST instead of failing the whole request. Every submitted entry consumes one unit of the daily quota; if the batch does not fit in the remaining quota the request returns 429 and nothing is consumed.", "tags": [ "V1" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinBatchLookupRequestSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinBatchLookupSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } }, "502": { "description": "HTTP 502", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BinLookupErrorResponse" } } } } } } } } }