List an organization's Pix keys

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

const options = {method: 'GET'};

fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict', 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",
  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"

	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")

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": "6728b1e2b4d3e80012c9a5a1",
    "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
    "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
    "accountId": "66f2a1c7b4d3e80012c9a0b4",
    "walletId": "66f2a3d1b4d3e80012c9a0d2",
    "environment": "LIVE",
    "account": {
      "bankIspb": "12345678",
      "branch": "001",
      "number": 10023456,
      "type": "TRAN"
    },
    "external": {
      "entryId": "b6f1d2c3-4e5a-4b7c-9d8e-1f2a3b4c5d6e"
    },
    "status": "ACTIVE",
    "type": "EVP",
    "value": "9f1c2e7a-4b3d-4e8f-a6c1-2d5b7e9f0a13",
    "createdAt": "2026-11-04T14:05:12.348Z",
    "updatedAt": "2026-11-04T14:05:12.348Z",
    "__v": 0,
    "failReason": "ENTRY_KEY_OWNED_BY_DIFFERENT_PARTICIPANT | The key is linked to another institution."
  }
]

{
  "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": "organizationId",
      "message": "Invalid UUID",
      "code": "ORGANIZATIONID_UUID"
    }
  ]
}

GET

realms

{realmId}

organizations

{organizationId}

pix-dict

List an organization's Pix keys

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

const options = {method: 'GET'};

fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/pix-dict', 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",
  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"

	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")

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": "6728b1e2b4d3e80012c9a5a1",
    "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
    "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
    "accountId": "66f2a1c7b4d3e80012c9a0b4",
    "walletId": "66f2a3d1b4d3e80012c9a0d2",
    "environment": "LIVE",
    "account": {
      "bankIspb": "12345678",
      "branch": "001",
      "number": 10023456,
      "type": "TRAN"
    },
    "external": {
      "entryId": "b6f1d2c3-4e5a-4b7c-9d8e-1f2a3b4c5d6e"
    },
    "status": "ACTIVE",
    "type": "EVP",
    "value": "9f1c2e7a-4b3d-4e8f-a6c1-2d5b7e9f0a13",
    "createdAt": "2026-11-04T14:05:12.348Z",
    "updatedAt": "2026-11-04T14:05:12.348Z",
    "__v": 0,
    "failReason": "ENTRY_KEY_OWNED_BY_DIFFERENT_PARTICIPANT | The key is linked to another institution."
  }
]

{
  "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": "organizationId",
      "message": "Invalid UUID",
      "code": "ORGANIZATIONID_UUID"
    }
  ]
}

The list is not paginated or sorted. Filter by status, which takes its values comma-separated (?status=ACTIVE,REMOVED). Only the keys of the environment in x-environment are listed, so send x-environment: LIVE for production keys. Removed keys and keys whose registration failed stay listed — filter by ACTIVE for the keys in use. Only an organization admin can list them.

Headers

x-environment

enum<string>

Environment whose Pix keys you list: LIVE (production) or TEST (sandbox). When you omit it, you get the TEST keys; 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

status

string[]

Only keys in these statuses (case-insensitive): ACTIVE, PENDING_CONFIRMATION, REMOVED or FAILED. Other values match no key; each value can have at most 64 characters.

Example: ?status=ACTIVE

Maximum string length: 64

Response

Successful response

_id

string

required

ID of the Pix key — use it as pixDictId.

Example:

"6728b1e2b4d3e80012c9a5a1"

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 key.

Example:

"66f2a3d1b4d3e80012c9a0d2"

environment

enum<string>

required

Environment of the key: LIVE or TEST.

Available options:

LIVE,

TEST

Example:

"LIVE"

account

object

required

The bank account the key points to.

Show child attributes

external

object

required

The key's identifiers in the Pix directory.

Show child attributes

status

enum<string>

required

Status of the key:

ACTIVE — registered: Pix sent to the key reach the wallet.
PENDING_CONFIRMATION — waiting for the confirmation code sent to the phone number or e-mail address (request one with request-otp, then confirm it).
REMOVED — removed from the wallet, or claimed by another institution. A removed key stays listed.
FAILED — registering failed; failReason says why. When the bank refused the key, nothing was registered; when it failed or didn't answer in time, the key may have been registered anyway.

Available options:

ACTIVE,

PENDING_CONFIRMATION,

REMOVED,

FAILED

Example:

"ACTIVE"

type

enum<string>

required

Kind of key: EVP (random key), CNPJ, CPF, EMAIL or PHONE.

Available options:

PHONE,

EMAIL,

CPF,

CNPJ,

EVP

Example:

"EVP"

value

string

required

The key: a lowercase UUID for EVP, digits only for CPF and CNPJ (a CNPJ may carry letters in its first 12 positions), a lowercase e-mail address, or a phone number as + and digits (+5511987654321). On a FAILED key, what was sent — empty for an EVP that was never generated.

Example:

"9f1c2e7a-4b3d-4e8f-a6c1-2d5b7e9f0a13"

createdAt

string

required

When the key was created (ISO 8601).

Example:

"2026-11-04T14:05:12.348Z"

updatedAt

string

required

When the key was last updated (ISO 8601).

Example:

"2026-11-04T14:05:12.348Z"

__v

number

required

Internal version of the record.

Example:

0

failReason

string

Why the registration was refused, as <code> | <message> — for example ENTRY_KEY_OWNED_BY_DIFFERENT_PERSON | The key already exists in the provider, but is linked to another person. Only on FAILED keys.

Example:

"ENTRY_KEY_OWNED_BY_DIFFERENT_PARTICIPANT | The key is linked to another institution."

Overview

Identity

Banking

Billing

Accounting

Registry

Platform

Notification

Rule Engine

Scheduling

Travel

Vehicles

Attachments

List an organization's Pix keys

Headers

Path Parameters

Query Parameters

Response