curl --request POST \
  --url https://api.example.com/v1/holder-removals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account": "0007654321",
  "accountId": "acc-123",
  "accountType": 0,
  "document": "82437485000140",
  "personType": 1,
  "branch": "0001",
  "ispb": "12345678"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/holder-removals"

	payload := strings.NewReader("{\n  \"account\": \"0007654321\",\n  \"accountId\": \"acc-123\",\n  \"accountType\": 0,\n  \"document\": \"82437485000140\",\n  \"personType\": 1,\n  \"branch\": \"0001\",\n  \"ispb\": \"12345678\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account: '0007654321',
    accountId: 'acc-123',
    accountType: 0,
    document: '82437485000140',
    personType: 1,
    branch: '0001',
    ispb: '12345678'
  })
};

fetch('https://api.example.com/v1/holder-removals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/holder-removals"

payload = {
    "account": "0007654321",
    "accountId": "acc-123",
    "accountType": 0,
    "document": "82437485000140",
    "personType": 1,
    "branch": "0001",
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "deletedKeys": [
    {
      "key": "foo@bar.com",
      "reason": 1,
      "result": 1,
      "document": "82437485000140",
      "name": "Empresa de Tal",
      "resultDescription": "Falha de comunicação com DICT"
    }
  ]
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Register a holder-ownership removal

Severs ONE holder’s ownership of a transactional account at the DICT (JDPI §8.2.05 Excluir Titular) and, as a consequence, has the DICT DELETE EVERY PIX key bound to that holder ON that account. The account itself stays open and the keys of its OTHER holders are untouched — that is the whole difference from POST /v1/account-closures, which closes the account and deletes every key on it regardless of holder.

Call it when a joint holder leaves, or when a holder’s link to the account ends for any other reason, after that holder has stopped transacting. Deletion at the DICT is not reversible: each key is gone from the national directory and has to be registered again to come back, which restarts its ownership and can open a claim if another institution claimed the key in the meantime.

The target holder is named by personType + document and is deliberately NOT inferred from accountId: the holder being removed is frequently not the one whose credentials made the call. The ISPB is resolved server-side from accountId and never read from the body.

⚠️ A 200 does NOT mean every deletion succeeded. The response carries one outcome row per key the DICT attempted; read result on each (1 = deleted, 0 = not deleted, with resultDescription giving the reason), because only the successes are mirrored into this plugin’s key projection. These rows are narrower than the account-closure ones — document and name are not populated here.

Refusals: 400 PIX-0061 when accountId or account is empty, or accountType is outside 0..4; 404 PIX-2016 when accountId does not resolve; 400 PIX-1000 when the DICT rejects a field, naming it; 404 PIX-1011 when the DICT knows no such holder-and-account binding or no keys under it; 422 PIX-1007 when the DICT refuses the removal in the current state; 503 PIX-1050 when the DICT is unreachable.

Which of this deployment’s direct participants writes to the national directory is decided by ispb, by exactly the rule an order’s payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.

POST

holder-removals

curl --request POST \
  --url https://api.example.com/v1/holder-removals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account": "0007654321",
  "accountId": "acc-123",
  "accountType": 0,
  "document": "82437485000140",
  "personType": 1,
  "branch": "0001",
  "ispb": "12345678"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/holder-removals"

	payload := strings.NewReader("{\n  \"account\": \"0007654321\",\n  \"accountId\": \"acc-123\",\n  \"accountType\": 0,\n  \"document\": \"82437485000140\",\n  \"personType\": 1,\n  \"branch\": \"0001\",\n  \"ispb\": \"12345678\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account: '0007654321',
    accountId: 'acc-123',
    accountType: 0,
    document: '82437485000140',
    personType: 1,
    branch: '0001',
    ispb: '12345678'
  })
};

fetch('https://api.example.com/v1/holder-removals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/holder-removals"

payload = {
    "account": "0007654321",
    "accountId": "acc-123",
    "accountType": 0,
    "document": "82437485000140",
    "personType": 1,
    "branch": "0001",
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "deletedKeys": [
    {
      "key": "foo@bar.com",
      "reason": 1,
      "result": 1,
      "document": "82437485000140",
      "name": "Empresa de Tal",
      "resultDescription": "Falha de comunicação com DICT"
    }
  ]
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Body

application/json

account

string

required

The account number.

Example:

"0007654321"

accountId

string

required

The CRM account id of the caller (resolves the server-side ISPB).

Example:

"acc-123"

accountType

integer<int64>

required

The account type (0=Checking,1=Salary,2=Savings,3=Payment,4=PI).

Example:

0

document

string

required

The target holder document (CPF/CNPJ).

Example:

"82437485000140"

personType

integer<int64>

required

The target holder person type (0=Person,1=Corporate).

Example:

1

branch

string

The branch number of the account.

Example:

"0001"

ispb

string

The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.

Pattern: ^[0-9]{8}$

Example:

"12345678"

Response

deletedKeys

object[] | null

required

The per-key deletion outcomes.

Show child attributes

Direct participant APIs

Indirect participant APIs

Register a holder-ownership removal

Authorizations

Body

Response