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 TokenYou 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.