v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB

DICT proxy lookup

Perform DICT proxy lookup

Submit a proxy lookup request against the DICT directory. Returns the created lookup with its current status. Owner and account fields are populated once status reaches sent.

post/proxy_services/dict/proxy_lookups

Request body

proxy_type_codestring required

The scheme-specific sub-type code for the proxy to look up.

proxy_identificationstring required

The proxy identifier to resolve.

connected_account_idstring uuid required

ID of the Mambu Payments connected account initiating the lookup.

Example request

{
  "proxy_type_code": "cpf",
  "proxy_identification": "12345678901",
  "connected_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheme_data": {
    "pi_payer_id": "12345678901",
    "pi_end_to_end_id": "E1234567820250101120000000000001",
    "pi_requesting_participant": "12345678"
  }
}

Response

Proxy lookup performed successfully

idstring uuid required

Unique identifier of the proxy lookup.

object'proxy_lookup' required

Object type label.

schemestring required

The directory scheme this lookup was performed against.

status'created' | 'processing' | 'sent' | 'completed' | 'rejected' required

Current state of the lookup request.

created — the request has been accepted.
processing — resolution is in progress.
sent — the lookup was dispatched to the scheme; awaiting resolution.
completed — resolved successfully; owner and account fields are populated.
rejected — the lookup could not be completed; status_reason carries the structured rejection code and status_details the human-readable text.

status_reasonstring nullable required

Structured reason code for the current status. Populated when status = rejected (carries the scheme rejection code: not_found, rate_limited, key_invalid, scheme_internal_error, forbidden). Null otherwise.

status_detailsstring nullable required

Free-text human-readable detail accompanying the current status. Carries the rejection text when status = rejected. Null otherwise.

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

The category of the resolved proxy identifier.

proxy_type_codestring nullable required

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

proxy_identificationstring required

The proxy identifier that was looked up.

owner_namestring nullable required

Full name of the resolved proxy key owner. Populated when status = completed, null otherwise.

owner_type'individual' | 'legal_entity' | 'null' nullable

Whether the resolved owner is an individual or a legal entity. Populated when status = completed, null otherwise.

account_identificationstring nullable required

Account number registered for this proxy. Populated when status = completed, null otherwise.

account_typestring nullable required

ISO 20022 account type code of the resolved account. Populated when status = completed, null otherwise.

account_issuerstring nullable required

Identifier of the institution that issued the resolved account. Populated when status = completed, null otherwise.

servicerstring nullable required

Identifier of the financial institution servicing the resolved account. Populated when status = completed, null otherwise.

connected_account_idstring uuid required

ID of the Mambu Payments connected account that initiated this lookup.

created_atstring date-time required

UTC timestamp when the lookup was created.

updated_atstring date-time nullable required

UTC timestamp of the last status update.

Example response

{
  "id": "d4e5f6a7-b8c9-0123-deff-012345678901",
  "object": "proxy_lookup",
  "scheme": "dict",
  "status": "sent",
  "proxy_type": "tax_id",
  "proxy_type_code": "cpf",
  "proxy_identification": "12345678901",
  "owner_name": "Maria Silva",
  "owner_type": "individual",
  "account_identification": "0001234-5",
  "account_type": "CACC",
  "account_issuer": "12345678",
  "servicer": "12345678",
  "connected_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheme_data": {
    "pi_payer_id": "12345678901",
    "pi_end_to_end_id": "E1234567820250101120000000000001",
    "pi_requesting_participant": "12345678",
    "owner_statistics": {},
    "key_statistics": {}
  },
  "created_at": "2025-01-01T12:00:00Z",
  "updated_at": "2025-01-01T12:00:01Z"
}