---
title: "Perform DICT proxy lookup"
method: POST
path: "/proxy_services/dict/proxy_lookups"
tags: ["DICT proxy lookup"]
---

# Perform DICT proxy lookup

`POST /proxy_services/dict/proxy_lookups`

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`.

## Request body

- DictProxyLookupCreationDetails — Details required to perform a DICT proxy lookup.
  - `proxy_type_code` string, required — The scheme-specific sub-type code for the proxy to look up.
  - `proxy_identification` string, required — The proxy identifier to resolve.
  - `connected_account_id` string, uuid, required — ID of the Mambu Payments connected account initiating the lookup.
  - `scheme_data` DictProxyLookupCreationSchemeData, required — DICT-mandatory payment instruction context required for a proxy lookup.
    - `pi_payer_id` string, required — ID of the payer in the payment instruction context (BACEN-required).
    - `pi_end_to_end_id` string, required — End-to-end ID of the payment instruction (BACEN-required).
    - `pi_requesting_participant` string, required — ISPB code of the requesting participant (BACEN-required).

## Response `200`

Proxy lookup performed successfully

- DictProxyLookup — A DICT proxy lookup result.
  - `id` string, uuid, required — Unique identifier of the proxy lookup.
  - `object` 'proxy_lookup', required — Object type label.
  - `scheme` string, 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_reason` string, 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_details` string, 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_code` string, nullable, required — The scheme-specific sub-type code of the resolved proxy.
  - `proxy_identification` string, required — The proxy identifier that was looked up.
  - `owner_name` string, 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_identification` string, nullable, required — Account number registered for this proxy. Populated when `status = completed`, null otherwise.
  - `account_type` string, nullable, required — ISO 20022 account type code of the resolved account. Populated when `status = completed`, null otherwise.
  - `account_issuer` string, nullable, required — Identifier of the institution that issued the resolved account. Populated when `status = completed`, null otherwise.
  - `servicer` string, nullable, required — Identifier of the financial institution servicing the resolved account. Populated when `status = completed`, null otherwise.
  - `connected_account_id` string, uuid, required — ID of the Mambu Payments connected account that initiated this lookup.
  - `scheme_data` DictProxyLookupSchemeData, required — DICT-specific output fields on a proxy lookup.
    - `pi_payer_id` string, required — Echoed payer ID from the payment instruction context.
    - `pi_end_to_end_id` string, required — Echoed end-to-end ID from the payment instruction context.
    - `pi_requesting_participant` string, required — Echoed ISPB of the requesting participant.
    - `owner_statistics` object, required — DICT statistics about the proxy key owner returned by the provider. Empty for the simulator.
    - `key_statistics` object, required — DICT statistics about the proxy key returned by the provider. Empty for the simulator.
  - `created_at` string, date-time, required — UTC timestamp when the lookup was created.
  - `updated_at` string, date-time, nullable, required — UTC timestamp of the last status update.

## Other responses

- `400` — Validation error.
- `404` — The specified resource was not found.

---

[API](https://skmtc.net/numeral/apis/payments.md) · [All operations](https://skmtc.net/numeral/apis/payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral/payments/versions/220f101cc2ef/schema)