v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB

DICT proxy claims

Create DICT proxy claim

Open a portability or ownership claim for a DICT proxy key registered at another institution.

Portability — the same person moves the key to a new institution. The claimer's tax ID must match the donor's.
Ownership — a new person claims a key (e.g. a reassigned phone number). Tax IDs do not need to match.

EVP (random alias) keys cannot be claimed and will result in a creation_rejected response.

If an active claim already exists for the proxy_identification, the request returns 409.

post/proxy_services/dict/proxy_claims

Request body

type'ownership' | 'portability' required

Whether the claim transfers the key to a new owner (ownership) or to the same owner at a new institution (portability).

proxy_type'phone' | 'email' | 'tax_id' | 'organisation' | 'random_alias' required

The category of proxy identifier being claimed.

The scheme-specific sub-type code for the proxy. Required when proxy_type is tax_id.

proxy_identificationstring required

The proxy identifier value to claim (e.g. CPF number, phone number).

claimer_namestring required

Full name of the claimer. Maximum 140 characters.

claimer_account_identificationstring required

Account number at the claiming institution.

claimer_account_type'CACC' | 'SVGS' | 'SLRY' | 'TRAN'

ISO 20022 account type code at the claiming institution.

claimer_account_issuerstring

Identifier of the institution that issued the claimer's account (e.g. branch code for DICT).

claimer_servicerstring required

ISPB of the claiming institution.

connected_account_idstring uuid required

ID of the Mambu Payments connected account associated with this claim.

internal_account_idstring uuid

Optional ID of an internal account in Mambu Payments linked to this claim.

metadataobject

Customer-defined key/value pairs passed through as-is.

Example request

{
  "type": "portability",
  "proxy_type": "tax_id",
  "proxy_type_code": "cpf",
  "proxy_identification": "12345678901",
  "claimer_name": "Maria Silva",
  "claimer_account_identification": "0001234-5",
  "claimer_account_type": "CACC",
  "claimer_account_issuer": "12345678",
  "claimer_servicer": "12345678",
  "connected_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "internal_account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "scheme_data": {
    "claimer_tax_identification_number": "12345678901",
    "claimer_owner_type": "individual",
    "claimer_opening_date": "2020-01-01T00:00:00Z"
  },
  "metadata": {}
}

Response

Proxy claim created. status is pending_creation when DICT accepted the request (flipped to open by the proxy_claim.creation_completed inbound event), or creation_rejected when DICT rejected it synchronously (e.g. key not found or not claimable).

idstring uuid required

Unique identifier of the proxy claim.

object'proxy_claim' required

Object type label.

schemestring required

The directory scheme this claim belongs to.

type'ownership' | 'portability' required

Claim type.

role'claimer' | 'donor' required

Whether our customer is opening the claim (claimer) or receiving it (donor).

Current state of the claim.

pending_creation — creation submitted to DICT; awaiting the scheme to finalise it (async). Flipped to open by proxy_claim.creation_completed or to creation_rejected by proxy_claim.creation_rejected.
open — DICT accepted the claim creation, awaiting donor response.
creation_rejected — DICT rejected the creation request (e.g. key not found or key type not claimable).
pending_acknowledgment — donor acknowledged the claim; awaiting the scheme to finalise it (async). Flipped to waiting_resolution by proxy_claim.acknowledgment_completed.
waiting_resolution — the donor's acknowledgment was finalised; waiting for the resolution period to complete.
acknowledgment_rejected — DICT rejected the donor's acknowledgment; status_details contains the rejection reason.
pending_confirmation — a confirm was requested; awaiting the scheme to finalise it (async). Flipped to confirmed by proxy_claim.confirmation_completed, which also releases the bound proxy key.
confirmed — donor confirmed the claim; the bound proxy key is released (status = disabled, status_reason = released_via_claim).
confirmation_rejected — DICT rejected the donor's confirmation; status_details contains the rejection reason.
pending_cancellation — a cancel was requested; awaiting the scheme to finalise it (async). Flipped to cancelled by proxy_claim.cancellation_completed. scheme_data.cancel_reason / scheme_data.cancelled_by are already populated.
cancelled — claim was cancelled; scheme_data.cancel_reason and scheme_data.cancelled_by are populated.
cancellation_rejected — DICT rejected the cancellation; status_details contains the rejection reason.
pending_completion — claimer requested completion; awaiting the scheme to finalise it (async). Flipped to completed by proxy_claim.completion_completed.
completed — claimer successfully completed the claim; proxy_key_id is populated with the new key.
completion_rejected — DICT rejected the completion request; status_details contains the rejection reason.

status_detailsstring nullable required

Additional information about the current status, populated when the claim is rejected.

proxy_type'phone' | 'email' | 'tax_id' | 'organisation' | 'random_alias' required

The category of the claimed proxy identifier.

proxy_type_codestring nullable required

The scheme-specific sub-type code of the claimed proxy.

proxy_identificationstring required

The proxy identifier value being claimed.

claimer_namestring required

Full name of the claimer.

claimer_account_identificationstring required

Account number at the claiming institution.

claimer_account_type'CACC' | 'SVGS' | 'SLRY' | 'TRAN' | 'null' nullable required

ISO 20022 account type code at the claiming institution.

claimer_account_issuerstring nullable required

Identifier of the institution that issued the claimer's account.

claimer_servicerstring required

ISPB of the claiming institution.

donor_servicerstring nullable required

ISPB of the institution currently holding the key. Populated once DICT resolves the donor.

connected_account_idstring uuid required

ID of the Mambu Payments connected account associated with this claim.

internal_account_idstring uuid nullable required

ID of the Mambu Payments internal account linked to this claim, if any.

proxy_key_idstring uuid nullable required

ID of the proxy key created upon successful completion of the claim. Null until the claim reaches completed status.

resolution_period_endstring date-time nullable required

Deadline by which the donor must respond. Null when status is creation_rejected.

completion_period_endstring date-time nullable required

Deadline by which the claim must reach a terminal state. Null when status is creation_rejected.

metadataobject required

Customer-defined key/value pairs.

created_atstring date-time required

UTC timestamp when the claim was created.

updated_atstring date-time nullable required

UTC timestamp of the last status update.

Example response

{
  "id": "e5f6a7b8-c9d0-1234-efff-123456789012",
  "object": "proxy_claim",
  "scheme": "dict",
  "type": "portability",
  "role": "claimer",
  "status": "open",
  "proxy_type": "tax_id",
  "proxy_type_code": "cpf",
  "proxy_identification": "12345678901",
  "claimer_name": "Maria Silva",
  "claimer_account_identification": "0001234-5",
  "claimer_account_type": "CACC",
  "claimer_account_issuer": "12345678",
  "claimer_servicer": "12345678",
  "connected_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resolution_period_end": "2026-01-08T12:00:00Z",
  "completion_period_end": "2026-01-15T12:00:00Z",
  "scheme_data": {
    "claim_id": "claim-bacen-uuid-001",
    "claimer_tax_identification_number": "12345678901",
    "claimer_owner_type": "individual",
    "claimer_opening_date": "2020-01-01T00:00:00Z"
  },
  "metadata": {},
  "created_at": "2026-01-01T12:00:00Z"
}