API Documentation

Let’s kick off with a simple example:

Example: Look up IIN/BIN in a single request

Below we find all cards having 12345678 as IIN/BIN.

curl https://api.iinlist.com/cards?iin=12345678
     --header "X-API-Key: $API_KEY"

A response will look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "count": 1,
  "_embedded": {
    "cards": [
      {
        "scheme": {
          "name": "Mastercard"
        },
        "product": {
          "name": "Standard Mastercard® Card",
          "segment": "consumer"
        },
        "account": {
          "funding": "credit",
          "country": {
            "code": "DK"
          }
        },
        "issuer": {
          "name": "BOKIS"
        },
        "fast_funds": {
          "domestic": true,
          "cross_border": true
        }
      }
    ]
  }
}

Introduction

Use our API to get up-to-date metadata about a payment card. Provide the first 6-8 digits (IIN/BIN) of a payment card number to get metadata such as country, account funding (debit or credit), product segment (consumer or business) etc.

What is an IIN/BIN?

The Issuer Identification Number (IIN) and Bank Identification Number (BIN) is the first 6-8 digits of a payment card number. They are two terms for the same thing and used interchangeably. For the remainder of this documentation we use Issuer Identification Number (IIN) for consistency.

 

The Issuer Identification Number (IIN) can be used to look up the account range of a payment card.

What is an account range?

A payment card number belongs to an account range having the associated metadata to be used in the payment ecosystem. An Issuer Identification Number (IIN) can be used to look up what account range a payment card number belongs to in order to get the metadata about the payment card. The account range is created in collabaration between a card scheme and an issuer.

What does IINlist do?

Our API does all the hard work of looking through the account ranges to identify a match with the provided Issuer Identification Number (IIN) and return the associated metadata. The metadata is returned as a card resource like shown in the example above.

 

We’ve done our best to make it as simple and effortless to use our API. Enjoy :)

Getting started

Base URL

The base URL is api.iinlist.com and functioning as the entry point of the API. Send a GET request to the base URL to explore the resources of the API.

curl https://api.iinlist.com

An example response can be seen under the root resource in the API reference.

Authentication

All URLs (except base url) require an API key specified in the X-API-Key header.

curl https://api.iinlist.com/cards?iin=12345678
     --header "X-API-Key: $API_KEY"

The API key is secret, so think about how you use and store it. Ensure it is not shown as clear text anywhere e.g in code, terminal etc - See recommendation for testing in the terminal. If you suspect somebody knows your API key please reach out to us immediately at [email protected], so we can disable it and issue a new one.

 

You can get an API key by signing up to one of our subscription plans.

Versioning

The latest version of the API is Version 1. All requests not specifying a version will receive the latest version of the API. We can specify the version through a media type parameter in the Accept header to avoid breaking changes when a new major version is released. An example of this is shown below in the sub-section Request Accept header.

Media types and content negotiation

The following media type and media type parameters are supported:

application/hal+json; charset=utf-8; version=1

Response Content-Type header

By default, all returned responses have the following Content-Type header:

Content-Type: application/hal+json; charset=utf-8; version=1

Request Accept header

To accommodate future media types and maybe changes in the default response Content-Type header, we should specify our preferences in the Accept header when making a request:

Accept: application/hal+json; charset=utf-8; version=1

In most of the examples in the documentation we’ve left out the Accept header for simplicity. However we still recommend it being specified by the client.

Errors

Errors will be communicated through the HTTP response status code and (for now) an empty JSON object as the response. An example of a 401 Unauthorized:

curl https://api.iinlist.com/cards?iin=12345678
HTTP/2 401
Content-Type: application/hal+json; charset=utf-8; version=1
...

{}

Recommendations

The following recommendations will provide tips on the integration and help make a flexible client for consuming the API.

Only provide 6-8 digits as an IIN

We should make sure to do not provide a full payment card number as an IIN. The API will not accept more than 8 digits, but logging mechanisms (maybe yours?) will often log the URL of a GET request where the IIN is provided to the API.

Allow for further property names and values to be added

Our plan is to continuously add property names and values to the returned resources. The client we build should allow for new property names and values to emerge on e.g. the returned Cards. If you are missing data, please reach out to us at [email protected].

Follow URLs, don’t hardcode them

We should save the base URL as our entry point, but the rest of the resources should be explored through the links. This will allow your client to just follow the resources without hardcoding the links. It will make it easy to explore and integrate new resources when they become available. See this external HAL page for more information about HAL - The (hyper)media type used by the API.

 

A HAL client following links would have code looking like the pseudocode:

root('api.iinlist.com').follow('cards').queryString('iin=12345678').get

With that being said. We have no intentions of changing any URLs if one decide on consuming the Cards directly via the shown URL.

Avoid API key showing up in the terminal

When testing the API through cURL we can do the following below to prevent the API key from floating around in the terminal.

1
2
3
4
5
read -s API_KEY &&
curl --request GET \
     --url https://api.iinlist.com/cards \
     --header "X-API-Key: $API_KEY"  \
&& unset API_KEY

When running the above, the terminal will ask for the API key in a masked field. After inserting the API key it is provided to the cURL request as a variable and the variable is unset when the request is finished. The commands can also be run seperately to read an api key to a variable and fire multiple requests before using the unset command. To do that remove both && and the \ in line 4.

API reference

The API consists of a Root resource and a collection of Card resources.

Root

The Root resource links to all resources in the API to make them discoverable. Currently, it only links to itself and to a collection of Card resources.

Supported HTTP Methods

GET

Request headers

Accept (recommended)

Example

The returned resource will provide a link to itself and the Cards collection.

curl https://api.iinlist.com \
     --header "Accept: application/hal+json; charset=utf-8; version=1"
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "_links": {
    "self": {
      "href": "https://api.iinlist.com"
    },
    "cards": {
      "href": "https://api.iinlist.com/cards{?iin,bin}",
      "templated": true
    }
  }
}

Cards

A collection of card resources can be queried based on a 6-8 digit IIN.

Supported HTTP Methods

GET

Request headers

X-API-Key (required),    Accept (recommended)

Query parameters

iin or bin (required, 6-8 digits)

Properties of a Card resource

Below are the properties of a Card resource. A client should allow for further property names and values to be added when e.g. a new card scheme is added or the ISO standard for a Country code is updated. The type of the property value e.g. string will not change.

  • Scheme: (object)
    • Name: Visa or Mastercard (string)
  • Product: (object)
    • Name: e.g. Visa Classic. (string)
    • Segment: consumer, business, commercial, government, all, other (string)
  • Account: (object)
    • Funding: credit, debit, prepaid, charge, deferred debit (string)
    • Country (object)
      • Code: Country code of the account (string, ISO 3166 Alpha-2 code)
  • Issuer: (object)
    • Name: Name of the issuer. (string)
  • Fast funds: (object)
    • Domestic: Indicates if fast funds is supported for Domestic. (boolean)
    • Cross Border: Indicates if fast funds is supported for cross-border (boolean)

Example

Below we find all cards having 12345678 as IIN/BIN.

curl https://api.iinlist.com/cards?iin=12345678
     --header "X-API-Key: $API_KEY"  \
     --header "Accept: application/hal+json; charset=utf-8; version=1"
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "count": 1,
  "_embedded": {
    "cards": [
      {
        "scheme": {
          "name": "Mastercard"
        },
        "product": {
          "name": "Standard Mastercard® Card",
          "segment": "consumer"
        },
        "account": {
          "funding": "credit",
          "country": {
            "code": "DK"
          }
        },
        "issuer": {
          "name": "BOKIS"
        },
        "fast_funds": {
          "domestic": true,
          "cross_border": true
        }
      }
    ]
  }
}