v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB

DICT proxy claims

Complete DICT proxy claim

Complete a proxy claim. Only the claimer side can call this endpoint (role = claimer). Completion rules depend on the claim type:

type=portability — completable once status = confirmed, regardless of deadline.
type=ownership — completable once status = confirmed and completion_period_end has passed.

Completion is async at the scheme. On success the response returns status = pending_completion: the request was accepted and is awaiting the scheme to finalise it. The claim is flipped to completed — and the new active proxy key created and linked via proxy_key_id — by the proxy_claim.completion_completed inbound event. On provider rejection the response returns 200 with status = completion_rejected and a populated status_details (rejections are stored business states, not HTTP errors).

post/proxy_services/dict/proxy_claims/{id}/complete

Path parameters

idstring uuid required

ID of the proxy claim to complete.

Response

Proxy claim moved to pending_completion (or completion rejected by the provider).

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