Endpoint responsible for listing the Pix keys registered in the authenticated Asaas account.

The listing can return all Pix keys in the account or only the keys that are in one or more specific statuses.

This endpoint is useful for integrations that need to consult existing keys before creating, displaying, validating, or removing a Pix key.

When to use

Use this endpoint when your integration needs to:

• list the Pix keys registered in the account;
• verify whether there is already an active Pix key;
• consult keys that are still awaiting activation;
• identify keys in the deletion process;
• validate whether a key can be removed;
• display available Pix keys in an administrative panel;
• synchronize the account’s Pix keys with the source system;
• consult the payload and the QR Code image associated with the key, when returned.

This endpoint only performs the consultation of keys. It does not create, activate, update, or remove Pix keys.

Query parameters

This endpoint accepts optional filters by pagination and status.

Available statuses

The status and statusList filters accept the following values:

Filter examples

List all keys

To list all Pix keys in the account, omit the status filters.

GET https://api.asaas.com/v3/pix/addressKeys

List keys by a single status

To list only the keys with a specific status, inform the status parameter.

GET https://api.asaas.com/v3/pix/addressKeys?status=ACTIVE

List keys by multiple statuses

To list keys with different statuses, inform the statusList parameter with the statuses separated by commas.

GET https://api.asaas.com/v3/pix/addressKeys?statusList=ACTIVE,AWAITING_DELETION

List keys with pagination

To control the number of records returned, use limit and offset.

GET https://api.asaas.com/v3/pix/addressKeys?limit=50&offset=0

Request example

curl --request GET \
  --url 'https://api-sandbox.asaas.com/v3/pix/addressKeys?status=ACTIVE&limit=100&offset=0' \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Response example

{
  "data": [
    {
      "id": "a33047b1-fb19-4b68-9373-a7ba8a8162aa",
      "key": "b6295ee1-f054-47d1-9e90-ee57b74f60d9",
      "type": "EVP",
      "status": "ACTIVE",
      "dateCreated": "2022-02-07 17:17:48",
      "canBeDeleted": true,
      "cannotBeDeletedReason": null,
      "qrCode": {
        "encodedImage": "QRCODE IMAGE IN BASE64",
        "payload": "00020126580014br.gov.bcb.pix0136a9fe43bc-164d-44d1-91c2-2f9b4d6956e95204000053039865802BR5925Joao da Silva6009Joinville62290525JOAOSILVA00000055ASA6304E62B"
      }
    }
  ]
}

Main response fields

Important behaviors

When using this endpoint, consider that:

• the listing returns only Pix keys linked to the authenticated account;
• the return can be filtered by a single status or by multiple statuses;
• the limit parameter has a maximum value of 100;
• for accounts with many keys, use pagination with offset and limit;
• keys in transitional statuses may change state after a new consultation;
• the qrCode field may contain useful information for display or payment via Pix;
• this endpoint does not change the state of the listed keys;
• GET calls must be performed without a body.

Pagination

To avoid very large responses, use pagination whenever your integration lists keys recurrently or in accounts with a high volume of records.

Pagination example:

First page:  limit=100&offset=0
Second page:   limit=100&offset=100
Third page:  limit=100&offset=200

Continue incrementing the offset until there are no more records to be processed.

Common errors

Some common errors when using this endpoint include:

Best practices

When implementing the listing of Pix keys, it is recommended to:

• use filters by status when it is not necessary to consult all keys;
• apply pagination with limit and offset;
• not send a body in GET requests;
• validate whether statusList is in the correct format, with statuses separated by commas;
• store the key id if your application needs to consult or remove the key later;
• validate canBeDeleted before trying to delete a Pix key;
• handle keys in transitional statuses with a new consultation before performing critical actions;
• avoid unnecessary consultations at very short intervals;
• protect returned data, such as Pix key and QR Code payload.

Operational impacts

The listing of Pix keys can be used in administrative and operational flows of the integration.

Some important impacts:

• a key with status ACTIVE can be used in Pix operations;
• a key in AWAITING_ACTIVATION may not yet be ready for use;
• a key in AWAITING_DELETION may not be available for new operations;
• a key with ERROR may require analysis before being used;
• the incorrect use of inactive or removed keys may cause failures in Pix charge or payment flows;
• consultations without pagination may make processing difficult in accounts with many keys.

Therefore, use filters and pagination appropriately according to the volume and purpose of the integration.

Related content

See also:

• Create Pix key;
• Retrieve Pix key;
• Remove Pix key;
• Create static QR Code;
• Pay a QR Code;
• Webhooks for Pix;
• What can be tested in Sandbox.