Parrot API Overview

The Parrot by Pagos BIN service is a very simple REST API that expects to receive—as input—a 6-8 digit BIN/IIN and whether the enhanced data should be included, and returns a simple JSON object back containing known details for the BIN.


Parrot doesn’t have a separate testing environment, but we do provide the ability to test a request and response by submitting a request with a valid API key; to do so, use the BIN: 999999.

Requests for information on this BIN will not use your quota or be billed.

For example:

curl -H "x-api-key:[your API key here]" ""

Error Handling

Any Pagos service errors will be presented in the following way:

{"message":[ERROR MESSAGE]}

Here are the possible values of the ERROR MESSAGE text:



Invalid input. BIN/IIN must be a string of numbers of length between 6 and 8.

You have provided an invalid BIN/IIN number.

Missing Authentication Token

You either didn't provide an API key or the provided API key is invalid.

Your trial period has expired. Please sign up for a plan or contact [email protected]

Your trial period has expired.

Exceeded trial period api calls quota. Please sign up for a plan or contact [email protected]

You have exceeded your quota of API calls during the trial period.

An internal error has occurred. Please contact [email protected]

Our system has encountered an error retrieving BIN/IIN information.

Invalid API key. Please contact [email protected]

Our system can't validate the provided API key.

Card BIN/IIN not found. Please contact [email protected]

We can't find the requested BIN/IIN.
This should be rare. We're always monitoring errors to establish if a data source can be found, but don’t hesitate to contact us if you have questions.