List an organization's Pix key claims

curl --request GET \
  --url https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim

const options = {method: 'GET'};

fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

[
  {
    "_id": "672a0c4fb4d3e80012c9a6b2",
    "id": "3b9e7c1a-5d2f-4e8b-9a61-0c4f2d7e8b13",
    "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
    "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
    "accountId": "66f2a1c7b4d3e80012c9a0b4",
    "walletId": "66f2a3d1b4d3e80012c9a0d2",
    "environment": "LIVE",
    "key": "12345678000190",
    "keyType": "CNPJ",
    "type": "portability",
    "status": "waiting",
    "claimer": {
      "document": "98.765.432/0001-10",
      "name": "Aurora Comércio Ltda",
      "type": "business"
    },
    "claimerAccount": {
      "accountNumber": 7654321,
      "accountType": "CACC",
      "branch": "1",
      "openingDate": "2021-03-15T00:00:00Z",
      "bankIspb": "60746948"
    },
    "donorBankIspb": 12345678,
    "external": {
      "accountId": "4f6b0e1d-2b3a-4c5d-8e9f-0a1b2c3d4e5f"
    },
    "insertedAt": "2026-11-03T23:25:04",
    "resolutionPeriodEnd": "2026-11-10T23:25:04Z",
    "createdAt": "2026-11-03T23:25:06.013Z",
    "updatedAt": "Tue Nov 03 2026 23:25:06 GMT+0000 (Coordinated Universal Time)",
    "__v": 0,
    "completionPeriodEnd": null,
    "cancelReason": null,
    "canceledBy": null,
    "confirmReason": null,
    "errorReason": null
  }
]

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "FORBIDDEN_WALLET",
  "origin": "BANKING",
  "message": "You do not have permission to perform this action on this wallet"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BAD_REQUEST",
  "origin": "BANKING",
  "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
  "fields": [
    {
      "field": "key",
      "message": "Too big: expected string to have <=77 characters",
      "code": "KEY_MAX"
    }
  ]
}

GET

realms

{realmId}

organizations

{organizationId}

pix-dict-claim

List an organization's Pix key claims

curl --request GET \
  --url https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim

const options = {method: 'GET'};

fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict-claim")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

[
  {
    "_id": "672a0c4fb4d3e80012c9a6b2",
    "id": "3b9e7c1a-5d2f-4e8b-9a61-0c4f2d7e8b13",
    "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
    "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
    "accountId": "66f2a1c7b4d3e80012c9a0b4",
    "walletId": "66f2a3d1b4d3e80012c9a0d2",
    "environment": "LIVE",
    "key": "12345678000190",
    "keyType": "CNPJ",
    "type": "portability",
    "status": "waiting",
    "claimer": {
      "document": "98.765.432/0001-10",
      "name": "Aurora Comércio Ltda",
      "type": "business"
    },
    "claimerAccount": {
      "accountNumber": 7654321,
      "accountType": "CACC",
      "branch": "1",
      "openingDate": "2021-03-15T00:00:00Z",
      "bankIspb": "60746948"
    },
    "donorBankIspb": 12345678,
    "external": {
      "accountId": "4f6b0e1d-2b3a-4c5d-8e9f-0a1b2c3d4e5f"
    },
    "insertedAt": "2026-11-03T23:25:04",
    "resolutionPeriodEnd": "2026-11-10T23:25:04Z",
    "createdAt": "2026-11-03T23:25:06.013Z",
    "updatedAt": "Tue Nov 03 2026 23:25:06 GMT+0000 (Coordinated Universal Time)",
    "__v": 0,
    "completionPeriodEnd": null,
    "cancelReason": null,
    "canceledBy": null,
    "confirmReason": null,
    "errorReason": null
  }
]

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "FORBIDDEN_WALLET",
  "origin": "BANKING",
  "message": "You do not have permission to perform this action on this wallet"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BAD_REQUEST",
  "origin": "BANKING",
  "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
  "fields": [
    {
      "field": "key",
      "message": "Too big: expected string to have <=77 characters",
      "code": "KEY_MAX"
    }
  ]
}

A claim is how a key moves between institutions. With a portability claim, the key’s owner asks another bank or payment institution to bring the key over from your wallet. With an ownership claim, someone else says a key you hold — an e-mail address or a phone number — is theirs. Answer a waiting claim before its resolutionPeriodEnd: confirm it to release the key, or cancel it to keep it. While a claim is open, the key can’t be removed. Filter by key. The list is not paginated or sorted, and settled claims stay listed. Only the claims of the environment in x-environment are listed, so send x-environment: LIVE for production claims. Only an organization admin can list them.

Headers

x-environment

enum<string>

Environment whose claims you list: LIVE (production) or TEST (sandbox). When you omit it, you get the TEST claims; any other value is rejected.

Available options:

LIVE,

TEST

Path Parameters

realmId

string<uuid>

required

ID of your realm.

Format: UUID

organizationId

string<uuid>

required

ID of the organization.

Format: UUID

Query Parameters

key

string

Only claims for this key, written exactly as it was registered (a CNPJ or CPF with digits only, an e-mail address in lowercase).

Maximum string length: 77

Response

Successful response

_id

string

required

Internal ID of the record. To confirm or cancel the claim, use id.

Example:

"672a0c4fb4d3e80012c9a6b2"

string

required

ID of the claim in the Pix directory — use it as id to confirm or cancel the claim.

Example:

"3b9e7c1a-5d2f-4e8b-9a61-0c4f2d7e8b13"

realmId

string

required

ID of the realm.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId

string

required

ID of the organization.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId

string

required

ID of the organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId

string

required

ID of the wallet that holds the claimed key.

Example:

"66f2a3d1b4d3e80012c9a0d2"

environment

enum<string>

required

Environment of the claim: LIVE or TEST.

Available options:

LIVE,

TEST

Example:

"LIVE"

key

string

required

The claimed key, as registered.

Example:

"12345678000190"

keyType

string

required

Kind of the claimed key: CNPJ, CPF, EMAIL or PHONE.

Example:

"CNPJ"

type

string

required

portability (the key's owner moves it to another institution) or ownership (someone else says the key is theirs).

Example:

"portability"

status

string

required

Status of the claim, as last notified:

waiting — waiting for your answer: confirm or cancel it before resolutionPeriodEnd.
processing_confirm — your confirmation is being processed.
confirmed — the claim was confirmed: the key is released to the claimer. It is marked REMOVED in your wallet when the Pix directory notifies the confirmation, which can come after the confirmation's response.
completed — the claimer's institution finished moving the key.
canceled — the claim was cancelled: the key stays in your wallet.

Other values the Pix directory defines may appear. A waiting claim past resolutionPeriodEnd may have been settled without a notification reaching us.

Example:

"waiting"

claimer

object

required

Who claims the key.

Show child attributes

claimerAccount

object

required

The account the claimer wants the key to point to, at the other institution.

Show child attributes

donorBankIspb

number

required

ISPB code of the institution that holds the key today — Portão 3's banking partner.

Example:

12345678

external

object

required

The claimed key's account identifiers at Portão 3's banking partner.

Show child attributes

insertedAt

string

required

When the claim was opened in the Pix directory (UTC, without a time zone suffix).

Example:

"2026-11-03T23:25:04"

resolutionPeriodEnd

string

required

Deadline to confirm or cancel the claim (ISO 8601, UTC).

Example:

"2026-11-10T23:25:04Z"

createdAt

string

required

When we received the claim (ISO 8601).

Example:

"2026-11-03T23:25:06.013Z"

updatedAt

string

required

When the record was last updated, as text in English with the time zone spelled out — not ISO 8601.

Example:

"Tue Nov 03 2026 23:25:06 GMT+0000 (Coordinated Universal Time)"

__v

number

required

Internal version of the record.

Example:

0

completionPeriodEnd

string | null

Deadline for the claim to be completed (ISO 8601, UTC), when the claim already carried one as it reached us — not updated afterwards. null or absent on most claims.

Example:

null

cancelReason

string | null

Reason the claim was cancelled, when the claim carried one as it reached us — not updated afterwards. null or absent: no claim received so far carried one.

Example:

null

canceledBy

string | null

Who cancelled the claim, when the claim carried it as it reached us — not updated afterwards. null or absent: no claim received so far carried it.

Example:

null

confirmReason

string | null

Reason the claim was confirmed, when the claim carried one as it reached us — not updated afterwards. null or absent: no claim received so far carried one.

Example:

null

errorReason

string | null

Error reported for the claim, when the claim carried one as it reached us — not updated afterwards. null or absent: no claim received so far carried one.

Example:

null

Overview

Identity

Banking

Billing

Accounting

Registry

Platform

Notification

Rule Engine

Scheduling

Travel

Vehicles

Attachments

List an organization's Pix key claims

Headers

Path Parameters

Query Parameters

Response