Parrot API v1 & v2 Overview


Parrot Versioning

This reference documentation refers to older versions of the Parrot API (v1 and v2). We no longer support onboarding new customers to Parrot v1 and v2 and don't make updates to the API Reference content.

If you're new to Parrot or already using Parrot API v3, see the Parrot API v3 Overview.

If you're unsure which version of Parrot you're using, contact your account manager for assistance.

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.

For example:

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



Requests for information on this BIN (999999) won't count towards your quota or be billed.

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.

Parrot IP Addresses

The following static IP addresses can be used to allowlist API traffic from Parrot: