Look up Pix key
Check the ownership of a Pix key
Look up the holder details of a Pix key to identify the recipient before making a transfer.
Lookups are controlled by two independent mechanisms: Rate Limit and Token Bucket. Both must be available for the lookup to be processed.
By the end of this guide, you will know how to look up a Pix key and track the balance available in the Token Bucket.
Lookup limits
Rate Limit
Up to 5 requests per minute per Asaas account are allowed. When this limit is exceeded, new lookups are temporarily blocked.
Token Bucket
The Token Bucket uses tokens to control the volume of lookups performed.
| Rule | Individual | Legal entity |
|---|---|---|
| Maximum limit | 60 tokens | 300 tokens |
| Valid lookup | -1 token | -1 token |
| Invalid lookup | -10 tokens | -15 tokens |
| Payment order received by the SPI | +1 token | +1 token |
| Time-based increment | +2 tokens per minute | +2 tokens per minute |
The limits apply to lookups by phone number, email, CPF, CNPJ, or random key.
When tokens run out, new lookups are blocked until the Token Bucket is replenished.
1. Check the token balance
Before performing lookups in volume, check the number of tokens available:
GET /pix/tokenBucket/addressKeySee the endpoint: Available Token Bucket Check.
If there are few tokens available, wait for the increment of 2 tokens per minute before continuing.
2. Look up the Pix key
Provide the type and the key you want to look up:
GET /pix/addressKeys/external?type=&key=Accepted values for type:
| Value | Key type |
|---|---|
CPF | CPF |
CNPJ | CNPJ |
EMAIL | |
PHONE | Phone number |
EVP | Random key |
See the endpoint: Check Pix key.
Sandbox limitationsIn Sandbox, you can only look up the Pix key
47996515839.The
cpfCnpjfield is returned masked, for example:***.202.745-**.
Next steps
Updated 2 days ago