Sign in

v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB
DICT proxy claims

Confirm DICT proxy claim

Donor confirms a proxy claim in waiting_resolution. On provider success the claim moves to pending_confirmation; on provider failure it moves to confirmation_rejected. Both outcomes return 200 — rejections are stored business states, not HTTP errors.

pending_confirmation is finalised asynchronously by the proxy_claim.confirmation_completed event, which transitions the claim to confirmed and — if it has a bound proxy_key_id — releases the linked proxy key (status = disabled, status_reason = released_via_claim) in the same transaction.

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

Path parameters

idstring uuid required

ID of the proxy claim to confirm.

Request body

Example request

{
  "scheme_data": {
    "reason": "USER_REQUESTED"
  }
}

Response

Confirm acknowledged — claim moved to pending_confirmation (or confirmation_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).

status'pending_creation' | 'open' | 'creation_rejected' | 'pending_acknowledgment' | 'waiting_resolution' | 'acknowledgment_rejected' | 'pending_confirmation' | 'confirmed' | 'confirmation_rejected' | 'pending_cancellation' | 'cancelled' | 'cancellation_rejected' | 'pending_completion' | 'completed' | 'completion_rejected' required

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