Retrieve a Pix key

Retrieves the details of a Pix key based on its value. When includeStatistics=true, the response includes key and owner statistics. When payerDocument is not provided, the lookup is restricted to internal cache and database; DICT is not queried and 404 is returned if the key is not found locally.

Path Parameters

key
Type: string
required

Pix key value (CPF, CNPJ, phone, email, or EVP)

Query Parameters

payerDocument
Type: string

Payer document (CPF or CNPJ). When present, the DICT is queried for the key entry; when absent, only the local cache is consulted and 404 is returned if the key is not found locally.
includeStatistics
Type: boolean

When true, includes anti-fraud statistics data in the response.
scheduledDate
Type: string Format: date

Settlement date of the scheduled payment this lookup is for (ISO yyyy-MM-dd). When present, the returned endToEndId embeds the predicted dispatch timestamp of that date instead of the lookup instant, so the identifier of the lookup is the one that settles. When absent, the lookup instant is used, as before.
endToEndId
Type: string

End-to-end identifier the caller already owns for the payment this lookup is for. When present, it is the PI-EndToEndId the DICT lookup travels under and the endToEndId returned, instead of one generated here — which is what lets the central bank credit the antiscan token back once the SPI receives the order carrying the same identifier. Takes precedence over scheduledDate, which only predicts an identifier. Malformed values are refused with 400 rather than forwarded to the DICT.

Headers

Idempotency-Key
Type: string
required

Unique idempotency key for the request

Responses

application/json

Código interno	HTTP	Descrição	Erro normativo Bacen
`KEYS-0028`	400	Key is blocked by court order and cannot be queried	`EntryBlocked`

application/json

application/json
application/json
application/json

Código interno	HTTP	Descrição	Erro normativo Bacen
`KEYS-0008`	404	Key not found	`EntryNotFound`

Código interno	HTTP	Descrição	Erro normativo Bacen
`KEYS-0009`	502, 503, 504	DICT integration failure	`ServiceUnavailable`

application/json

Código interno	HTTP	Descrição	Erro normativo Bacen
`KEYS-0009`	502, 503, 504	DICT integration failure	`ServiceUnavailable`

Código interno	HTTP	Descrição	Erro normativo Bacen
`KEYS-0009`	502, 503, 504	DICT integration failure	`ServiceUnavailable`

get/api/v1/keys/{key}

curl 'http://localhost/api/v1/keys/{key}' \
  --header 'Idempotency-Key: ' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "string",
  "status": "ACTIVE",
  "keyType": "EVP",
  "key": "string",
  "owner": {
    "personType": "string",
    "taxId": "string",
    "name": "string",
    "tradeName": "string"
  },
  "account": {
    "ispb": "string",
    "type": "string",
    "branch": "string",
    "number": "string",
    "openingDate": "2026-09-16T19:14:18.660Z"
  },
  "reason": "USER_REQUESTED",
  "keyOwnershipDate": "2026-09-16T19:14:18.660Z",
  "createdAt": "2026-09-16T19:14:18.660Z",
  "updatedAt": "2026-09-16T19:14:18.660Z",
  "creationDate": "2026-09-16T19:14:18.660Z",
  "openClaimCreationDate": "2026-09-16T19:14:18.660Z",
  "endToEndId": "string",
  "ownerStatistics": {
    "spi": {
      "watermark": "2026-09-16T19:14:18.660Z",
      "settlements": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      }
    },
    "fraudMarkers": {
      "watermark": "2026-09-16T19:14:18.660Z",
      "applicationFrauds": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "muleAccounts": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "scammerAccounts": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "otherFrauds": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "unknownFrauds": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "totalFraudTransactionAmount": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "distinctFraudReporters": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      }
    },
    "infractionReports": {
      "watermark": "2026-09-16T19:14:18.660Z",
      "openReports": 1,
      "openReportsDistinctReporters": 1,
      "rejectedReports": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      }
    },
    "entries": {
      "watermark": "2026-09-16T19:14:18.660Z",
      "registeredAccounts": 1
    }
  },
  "keyStatistics": {
    "spi": {
      "watermark": "2026-09-16T19:14:18.660Z",
      "settlements": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      }
    },
    "fraudMarkers": {
      "watermark": "2026-09-16T19:14:18.660Z",
      "applicationFrauds": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "muleAccounts": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "scammerAccounts": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "otherFrauds": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "unknownFrauds": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "totalFraudTransactionAmount": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      },
      "distinctFraudReporters": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      }
    },
    "infractionReports": {
      "watermark": "2026-09-16T19:14:18.660Z",
      "openReports": 1,
      "openReportsDistinctReporters": 1,
      "rejectedReports": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      }
    },
    "entries": {
      "watermark": "2026-09-16T19:14:18.660Z",
      "distinctAccounts": {
        "d90": 1,
        "m12": 1,
        "m60": 1
      }
    }
  }
}

Pix key retrieved successfully.