{"openapi":"3.1.0","x-internal":true,"info":{"title":"Proxy Lookup","description":"Resolve and manage payee proxy keys (e.g. Brazilian DICT). The proxy\nlookup service exposes two related objects:\n  - `proxy_key` — a payee-side directory entry registered against a\n    connected account.\n  - `proxy_lookup` — a payer-side resolution request that returns\n    the owner / account details registered for a given proxy.\n","version":"1","contact":{"name":"API Support","email":"dev@numeral.io"}},"tags":[{"name":"DICT Proxy Keys","description":"Proxy keys (payee-side directory entries)"},{"name":"DICT Proxy Lookup","description":"Proxy lookups (payer-side resolution requests)"},{"name":"DICT Proxy Claims","description":"DICT proxy key portability and ownership claims (claimer side)"}],"servers":[{"url":"https://sandbox.numeral.io/v1"}],"components":{"securitySchemes":{"sec0":{"type":"apiKey","in":"header","name":"x-api-key"}},"parameters":{"proxy_keys.list_parameters.limit":{"name":"limit","in":"query","description":"Maximum number of records to return (1–100). Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"proxy_keys.list_parameters.starting_after":{"name":"starting_after","in":"query","description":"The ID of the object from which your list request will start. It is not included in the result.","schema":{"type":"string","format":"uuid"}},"proxy_lookups.list_parameters.limit":{"name":"limit","in":"query","description":"Maximum number of records to return (1–100). Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"proxy_lookups.list_parameters.starting_after":{"name":"starting_after","in":"query","description":"The ID of the object from which your list request will start. It is not included in the result.","schema":{"type":"string","format":"uuid"}},"proxy_claims.list_parameters.limit":{"name":"limit","in":"query","description":"Maximum number of records to return (1–100). Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"proxy_claims.list_parameters.starting_after":{"name":"starting_after","in":"query","description":"The ID of the object from which your list request will start. It is not included in the result.","schema":{"type":"string","format":"uuid"}}},"responses":{"errors.400.validation":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"errors.404.not_found":{"description":"The specified resource was not found."},"errors.409.conflict":{"description":"Conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}},"schemas":{"error":{"type":"object","properties":{"error":{"type":"string","example":"validation_error"},"message":{"type":"string","example":"validation errors occurred while processing request"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"reason":{"type":"string"}}}},"correlation_id":{"type":"string","format":"uuid"}}},"dict_proxy_key.creation_details":{"type":"object","description":"Details required to register a DICT proxy key.","required":["owner_type","proxy_type","proxy_identification","owner_name","account_identification","servicer","connected_account_id","scheme_data"],"properties":{"owner_type":{"type":"string","description":"Whether the proxy key owner is an individual or a legal entity.","enum":["individual","legal_entity"],"example":"individual"},"proxy_type":{"type":"string","description":"The category of proxy identifier (phone number, email, tax ID, etc.).","enum":["phone","email","tax_id","organisation","random_alias"],"example":"tax_id"},"proxy_type_code":{"type":"string","description":"The scheme-specific sub-type code for the proxy. For DICT: `cpf` (individual) or `cnpj` (legal entity).","enum":["cpf","cnpj","abn","teli","emal","aubn","orgn","evp"],"example":"cpf"},"proxy_identification":{"type":"string","description":"The proxy identifier value (e.g. the CPF number, email address, or phone number).","example":"12345678901"},"owner_name":{"type":"string","description":"Full name of the proxy key owner. Maximum 140 characters.","maxLength":140,"example":"Maria Silva"},"account_identification":{"type":"string","description":"Account number associated with this proxy key.","example":"0001234-5"},"account_type":{"type":"string","description":"ISO 20022 account type code.","enum":["CACC","SVGS","SLRY","TRAN"],"example":"CACC"},"account_issuer":{"type":"string","description":"Identifier of the institution that issued the account (e.g. ISPB code for DICT).","example":"12345678"},"servicer":{"type":"string","description":"Identifier of the financial institution servicing the account (e.g. ISPB for DICT).","example":"12345678"},"connected_account_id":{"type":"string","format":"uuid","description":"ID of the Mambu Payments connected account to register this proxy key against.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"internal_account_id":{"type":"string","format":"uuid","description":"Optional ID of an internal account in Mambu Payments linked to this proxy key.","example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"scheme_data":{"$ref":"#/components/schemas/dict_proxy_key.creation_scheme_data"},"metadata":{"type":"object","additionalProperties":true,"description":"Customer-defined key/value pairs passed through as-is.","example":{"customer_ref":"cust-001"}}}},"dict_proxy_key.creation_scheme_data":{"type":"object","description":"DICT-specific input fields required when registering a proxy key.","required":["reason","tax_identification_number"],"properties":{"reason":{"type":"string","description":"Reason for registering the proxy key in the DICT directory.","enum":["USER_REQUESTED","RECONCILIATION"],"example":"USER_REQUESTED"},"tax_identification_number":{"type":"string","description":"Tax identification number (CPF or CNPJ) of the proxy key owner.","example":"12345678901"}}},"dict_proxy_key.update_details":{"type":"object","description":"Fields to update on an active DICT proxy key. All fields are optional;\nomitted fields are left unchanged. An empty body is a valid no-op — the\ncurrent key is returned.\n","properties":{"owner_name":{"type":"string","description":"Full name of the proxy key owner. Maximum 140 characters.","maxLength":140,"example":"João Santos"},"account_identification":{"type":"string","description":"Account number associated with this proxy key.","example":"0009876-5"},"account_type":{"type":["string","null"],"description":"ISO 20022 account type code. Pass null to clear the existing value.","enum":["CACC","SVGS","SLRY","TRAN",null],"example":"CACC"},"account_issuer":{"type":["string","null"],"description":"Identifier of the institution that issued the account. Pass null to clear the existing value.","example":"12345678"},"servicer":{"type":"string","description":"Identifier of the financial institution servicing the account.","example":"12345678"},"metadata":{"type":"object","additionalProperties":true,"description":"Shallow key/value patch applied to the existing metadata:\nkeys present in the patch overwrite existing values; setting a key\nto null removes it from the stored metadata; keys absent from the\npatch are preserved.\n","example":{"customer_ref":"cust-002"}}}},"dict_proxy_key":{"type":"object","description":"A DICT proxy key registered in the directory.","required":["id","object","scheme","owner_type","owner_name","proxy_type","proxy_type_code","proxy_identification","status","status_details","status_reason","account_identification","account_type","account_issuer","connected_account_id","internal_account_id","servicer","scheme_data","metadata","created_at","disabled_at","enabled_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the proxy key.","example":"c39d1eff-c5ed-4197-8f24-28a68bd0eee6"},"object":{"type":"string","enum":["proxy_key"],"description":"Object type label.","example":"proxy_key"},"scheme":{"type":"string","description":"The directory scheme this proxy key is registered in.","example":"dict"},"owner_type":{"type":"string","description":"Whether the owner is an individual or a legal entity.","enum":["individual","legal_entity"],"example":"individual"},"owner_name":{"type":"string","description":"Full name of the proxy key owner.","example":"Maria Silva"},"proxy_type":{"type":"string","description":"The category of proxy identifier.","enum":["phone","email","tax_id","organisation","random_alias"],"example":"tax_id"},"proxy_type_code":{"type":["string","null"],"description":"The scheme-specific sub-type code for the proxy.","enum":["cpf","cnpj","abn","teli","emal","aubn","orgn","evp",null],"example":"cpf"},"proxy_identification":{"type":"string","description":"The proxy identifier value.","example":"12345678901"},"status":{"type":"string","description":"Current status of the proxy key.","enum":["active","disabled"],"example":"active"},"status_details":{"type":["string","null"],"description":"Additional information about the current status.","example":null},"status_reason":{"type":["string","null"],"description":"Machine-readable reason the key reached its current status. `released_via_claim` when disabled by a confirmed donor-side claim.","enum":["released_via_claim",null],"example":null},"account_identification":{"type":"string","description":"Account number associated with this proxy key.","example":"0001234-5"},"account_type":{"type":["string","null"],"description":"ISO 20022 account type code.","enum":["CACC","SVGS","SLRY","TRAN",null],"example":"CACC"},"account_issuer":{"type":["string","null"],"description":"Identifier of the institution that issued the account.","example":"12345678"},"connected_account_id":{"type":"string","format":"uuid","description":"ID of the Mambu Payments connected account this proxy key is registered against.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"internal_account_id":{"type":["string","null"],"format":"uuid","description":"ID of the Mambu Payments internal account linked to this proxy key, if any.","example":null},"servicer":{"type":"string","description":"Identifier of the financial institution servicing the account.","example":"12345678"},"scheme_data":{"$ref":"#/components/schemas/dict_proxy_key.scheme_data"},"metadata":{"type":"object","additionalProperties":true,"description":"Customer-defined key/value pairs.","example":{"customer_ref":"cust-001"}},"created_at":{"type":"string","format":"date-time","description":"UTC timestamp when the proxy key was created.","example":"2025-01-01T12:00:00Z"},"disabled_at":{"type":["string","null"],"format":"date-time","description":"UTC timestamp when the proxy key was disabled, if applicable.","example":null},"enabled_at":{"type":["string","null"],"format":"date-time","description":"UTC timestamp when the proxy key was last enabled, if applicable.","example":null}}},"dict_proxy_key.scheme_data":{"type":"object","description":"DICT-specific output fields on a proxy key.","required":["reason","tax_identification_number","directory_entry_id"],"properties":{"reason":{"type":"string","description":"Reason for which the proxy key was registered.","example":"USER_REQUESTED"},"tax_identification_number":{"type":"string","description":"Tax identification number of the proxy key owner.","example":"12345678901"},"directory_entry_id":{"type":"string","description":"BACEN directory entry ID returned by the provider when the key was registered.","example":"dict-entry-abc123"}}},"dict_proxy_key.list_result":{"type":"object","description":"Paginated list of DICT proxy keys.","required":["records"],"properties":{"records":{"type":"array","description":"List of proxy keys matching the query.","items":{"$ref":"#/components/schemas/dict_proxy_key"}}}},"dict_proxy_lookup.creation_details":{"type":"object","description":"Details required to perform a DICT proxy lookup.","required":["proxy_type_code","proxy_identification","connected_account_id","scheme_data"],"properties":{"proxy_type_code":{"type":"string","description":"The scheme-specific sub-type code for the proxy to look up.","example":"cpf"},"proxy_identification":{"type":"string","description":"The proxy identifier to resolve.","example":"12345678901"},"connected_account_id":{"type":"string","format":"uuid","description":"ID of the Mambu Payments connected account initiating the lookup.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"scheme_data":{"$ref":"#/components/schemas/dict_proxy_lookup.creation_scheme_data"}}},"dict_proxy_lookup.creation_scheme_data":{"type":"object","description":"DICT-mandatory payment instruction context required for a proxy lookup.","required":["pi_payer_id","pi_end_to_end_id","pi_requesting_participant"],"properties":{"pi_payer_id":{"type":"string","description":"ID of the payer in the payment instruction context (BACEN-required).","example":"12345678901"},"pi_end_to_end_id":{"type":"string","description":"End-to-end ID of the payment instruction (BACEN-required).","example":"E1234567820250101120000000000001"},"pi_requesting_participant":{"type":"string","description":"ISPB code of the requesting participant (BACEN-required).","example":"12345678"}}},"dict_proxy_lookup":{"type":"object","description":"A DICT proxy lookup result.","required":["id","object","scheme","status","status_details","proxy_type","proxy_type_code","proxy_identification","owner_name","account_identification","account_type","account_issuer","servicer","connected_account_id","scheme_data","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the proxy lookup.","example":"d4e5f6a7-b8c9-0123-deff-012345678901"},"object":{"type":"string","enum":["proxy_lookup"],"description":"Object type label.","example":"proxy_lookup"},"scheme":{"type":"string","description":"The directory scheme this lookup was performed against.","example":"dict"},"status":{"type":"string","description":"Current state of the lookup request.\n- `created` — the request has been accepted.\n- `processing` — resolution is in progress.\n- `sent` — resolved successfully; owner and account fields are populated.\n- `completed` — reserved; not currently returned.\n- `rejected` — the lookup could not be completed; `status_details` contains the reason.\n","enum":["created","processing","sent","completed","rejected"],"example":"sent"},"status_details":{"type":["string","null"],"description":"Additional information about the lookup status.","example":null},"proxy_type":{"type":"string","description":"The category of the resolved proxy identifier.","enum":["phone","email","tax_id","organisation","random_alias"],"example":"tax_id"},"proxy_type_code":{"type":["string","null"],"description":"The scheme-specific sub-type code of the resolved proxy.","example":"cpf"},"proxy_identification":{"type":"string","description":"The proxy identifier that was looked up.","example":"12345678901"},"owner_name":{"type":["string","null"],"description":"Full name of the proxy key owner. Populated when `status = sent`, null otherwise.","example":"Maria Silva"},"account_identification":{"type":["string","null"],"description":"Account number registered for this proxy. Populated when `status = sent`, null otherwise.","example":"0001234-5"},"account_type":{"type":["string","null"],"description":"ISO 20022 account type code of the resolved account.","example":"CACC"},"account_issuer":{"type":["string","null"],"description":"Identifier of the institution that issued the resolved account.","example":"12345678"},"servicer":{"type":["string","null"],"description":"Identifier of the financial institution servicing the resolved account.","example":"12345678"},"connected_account_id":{"type":"string","format":"uuid","description":"ID of the Mambu Payments connected account that initiated this lookup.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"scheme_data":{"$ref":"#/components/schemas/dict_proxy_lookup.scheme_data"},"created_at":{"type":"string","format":"date-time","description":"UTC timestamp when the lookup was created.","example":"2025-01-01T12:00:00Z"},"updated_at":{"type":["string","null"],"format":"date-time","description":"UTC timestamp of the last status update.","example":"2025-01-01T12:00:01Z"}}},"dict_proxy_lookup.scheme_data":{"type":"object","description":"DICT-specific output fields on a proxy lookup.","required":["pi_payer_id","pi_end_to_end_id","pi_requesting_participant","owner_statistics","key_statistics"],"properties":{"pi_payer_id":{"type":"string","description":"Echoed payer ID from the payment instruction context.","example":"12345678901"},"pi_end_to_end_id":{"type":"string","description":"Echoed end-to-end ID from the payment instruction context.","example":"E1234567820250101120000000000001"},"pi_requesting_participant":{"type":"string","description":"Echoed ISPB of the requesting participant.","example":"12345678"},"owner_statistics":{"type":"object","additionalProperties":true,"description":"DICT statistics about the proxy key owner returned by the provider. Empty for the simulator.","example":{}},"key_statistics":{"type":"object","additionalProperties":true,"description":"DICT statistics about the proxy key returned by the provider. Empty for the simulator.","example":{}}}},"dict_proxy_lookup.list_result":{"type":"object","description":"Paginated list of DICT proxy lookups.","required":["records"],"properties":{"records":{"type":"array","description":"List of proxy lookups matching the query.","items":{"$ref":"#/components/schemas/dict_proxy_lookup"}}}},"dict_proxy_claim.creation_details":{"type":"object","description":"Details required to open a DICT proxy key portability or ownership claim.","required":["type","proxy_type","proxy_identification","claimer_name","claimer_account_identification","claimer_servicer","connected_account_id","scheme_data"],"properties":{"type":{"type":"string","description":"Whether the claim transfers the key to a new owner (`ownership`) or to the same owner at a new institution (`portability`).","enum":["ownership","portability"],"example":"portability"},"proxy_type":{"type":"string","description":"The category of proxy identifier being claimed.","enum":["phone","email","tax_id","organisation","random_alias"],"example":"tax_id"},"proxy_type_code":{"type":"string","description":"The scheme-specific sub-type code for the proxy. Required when `proxy_type` is `tax_id`.","enum":["cpf","cnpj","abn","teli","emal","aubn","orgn","evp"],"example":"cpf"},"proxy_identification":{"type":"string","description":"The proxy identifier value to claim (e.g. CPF number, phone number).","example":"12345678901"},"claimer_name":{"type":"string","description":"Full name of the claimer. Maximum 140 characters.","maxLength":140,"example":"Maria Silva"},"claimer_account_identification":{"type":"string","description":"Account number at the claiming institution.","example":"0001234-5"},"claimer_account_type":{"type":"string","description":"ISO 20022 account type code at the claiming institution.","enum":["CACC","SVGS","SLRY","TRAN"],"example":"CACC"},"claimer_account_issuer":{"type":"string","description":"Identifier of the institution that issued the claimer's account (e.g. branch code for DICT).","example":"12345678"},"claimer_servicer":{"type":"string","description":"ISPB of the claiming institution.","example":"12345678"},"connected_account_id":{"type":"string","format":"uuid","description":"ID of the Mambu Payments connected account associated with this claim.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"internal_account_id":{"type":"string","format":"uuid","description":"Optional ID of an internal account in Mambu Payments linked to this claim.","example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"scheme_data":{"$ref":"#/components/schemas/dict_proxy_claim.creation_scheme_data"},"metadata":{"type":"object","additionalProperties":true,"description":"Customer-defined key/value pairs passed through as-is.","example":{}}}},"dict_proxy_claim.creation_scheme_data":{"type":"object","description":"DICT-specific fields required to open a proxy claim.","required":["claimer_tax_identification_number","claimer_owner_type","claimer_opening_date"],"properties":{"claimer_tax_identification_number":{"type":"string","description":"Tax identification number (CPF or CNPJ) of the claimer.","example":"12345678901"},"claimer_owner_type":{"type":"string","description":"Whether the claimer is an individual or a legal entity.","enum":["individual","legal_entity"],"example":"individual"},"claimer_opening_date":{"type":"string","format":"date-time","description":"Date and time the claimer's account was opened at the claiming institution (BACEN-required).","example":"2020-01-01T00:00:00Z"}}},"dict_proxy_claim.confirm_details":{"type":"object","description":"Details required to confirm a waiting DICT proxy claim.","required":["scheme_data"],"properties":{"scheme_data":{"$ref":"#/components/schemas/dict_proxy_claim.confirm_scheme_data"}}},"dict_proxy_claim.confirm_scheme_data":{"type":"object","description":"DICT-specific fields required to confirm a proxy claim.","required":["reason"],"properties":{"reason":{"type":"string","description":"Reason for confirming the claim.","enum":["USER_REQUESTED","ACCOUNT_CLOSURE","DEFAULT_OPERATION"],"example":"USER_REQUESTED"}}},"dict_proxy_claim.cancel_details":{"type":"object","description":"Request body for POST /v1/proxy_services/dict/proxy_claims/{id}/cancel.","required":["scheme_data"],"properties":{"scheme_data":{"$ref":"#/components/schemas/dict_proxy_claim.cancel_scheme_data"}}},"dict_proxy_claim.cancel_scheme_data":{"type":"object","description":"DICT-specific fields required to cancel a proxy claim.","required":["reason"],"properties":{"reason":{"type":"string","description":"Reason for cancelling the claim.","enum":["USER_REQUESTED","ACCOUNT_CLOSURE","FRAUD","DEFAULT_OPERATION","RECONCILIATION","RFB_VALIDATION"],"example":"USER_REQUESTED"}}},"dict_proxy_claim":{"type":"object","description":"A DICT proxy key portability or ownership claim.","required":["id","object","scheme","type","role","status","status_details","proxy_type","proxy_type_code","proxy_identification","claimer_name","claimer_account_identification","claimer_account_type","claimer_account_issuer","claimer_servicer","donor_servicer","connected_account_id","internal_account_id","proxy_key_id","resolution_period_end","completion_period_end","scheme_data","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the proxy claim.","example":"e5f6a7b8-c9d0-1234-efff-123456789012"},"object":{"type":"string","enum":["proxy_claim"],"description":"Object type label.","example":"proxy_claim"},"scheme":{"type":"string","description":"The directory scheme this claim belongs to.","example":"dict"},"type":{"type":"string","description":"Claim type.","enum":["ownership","portability"],"example":"portability"},"role":{"type":"string","description":"Whether our customer is opening the claim (`claimer`) or receiving it (`donor`).","enum":["claimer","donor"],"example":"claimer"},"status":{"type":"string","description":"Current state of the claim.\n- `open` — submitted to DICT, awaiting donor response.\n- `creation_rejected` — DICT rejected the creation request (e.g. key not found or key type not claimable).\n- `waiting_resolution` — donor acknowledged the claim; waiting for the resolution period to complete.\n- `acknowledgment_rejected` — DICT rejected the donor's acknowledgment; `status_details` contains the rejection reason.\n- `confirmed` — donor confirmed the claim; the bound proxy key is released.\n- `confirmation_rejected` — DICT rejected the donor's confirmation; `status_details` contains the rejection reason.\n- `cancelled` — claim was cancelled; `scheme_data.cancel_reason` and `scheme_data.cancelled_by` are populated.\n- `cancellation_rejected` — DICT rejected the cancellation; `status_details` contains the rejection reason.\n- `completed` — claimer successfully completed the claim; `proxy_key_id` is populated with the new key.\n- `completion_rejected` — DICT rejected the completion request; `status_details` contains the rejection reason.\n","enum":["open","creation_rejected","waiting_resolution","acknowledgment_rejected","confirmed","confirmation_rejected","cancelled","cancellation_rejected","completed","completion_rejected"],"example":"open"},"status_details":{"type":["string","null"],"description":"Additional information about the current status, populated when the claim is rejected.","example":null},"proxy_type":{"type":"string","description":"The category of the claimed proxy identifier.","enum":["phone","email","tax_id","organisation","random_alias"],"example":"tax_id"},"proxy_type_code":{"type":["string","null"],"description":"The scheme-specific sub-type code of the claimed proxy.","example":"cpf"},"proxy_identification":{"type":"string","description":"The proxy identifier value being claimed.","example":"12345678901"},"claimer_name":{"type":"string","description":"Full name of the claimer.","example":"Maria Silva"},"claimer_account_identification":{"type":"string","description":"Account number at the claiming institution.","example":"0001234-5"},"claimer_account_type":{"type":["string","null"],"description":"ISO 20022 account type code at the claiming institution.","enum":["CACC","SVGS","SLRY","TRAN",null],"example":"CACC"},"claimer_account_issuer":{"type":["string","null"],"description":"Identifier of the institution that issued the claimer's account.","example":"12345678"},"claimer_servicer":{"type":"string","description":"ISPB of the claiming institution.","example":"12345678"},"donor_servicer":{"type":["string","null"],"description":"ISPB of the institution currently holding the key. Populated once DICT resolves the donor.","example":null},"connected_account_id":{"type":"string","format":"uuid","description":"ID of the Mambu Payments connected account associated with this claim.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"internal_account_id":{"type":["string","null"],"format":"uuid","description":"ID of the Mambu Payments internal account linked to this claim, if any.","example":null},"proxy_key_id":{"type":["string","null"],"format":"uuid","description":"ID of the proxy key created upon successful completion of the claim. Null until the claim reaches `completed` status.","example":null},"resolution_period_end":{"type":["string","null"],"format":"date-time","description":"Deadline by which the donor must respond. Null when `status` is `creation_rejected`.","example":"2026-01-08T12:00:00Z"},"completion_period_end":{"type":["string","null"],"format":"date-time","description":"Deadline by which the claim must reach a terminal state. Null when `status` is `creation_rejected`.","example":"2026-01-15T12:00:00Z"},"scheme_data":{"$ref":"#/components/schemas/dict_proxy_claim.scheme_data"},"metadata":{"type":"object","additionalProperties":true,"description":"Customer-defined key/value pairs.","example":{}},"created_at":{"type":"string","format":"date-time","description":"UTC timestamp when the claim was created.","example":"2026-01-01T12:00:00Z"},"updated_at":{"type":["string","null"],"format":"date-time","description":"UTC timestamp of the last status update.","example":null}}},"dict_proxy_claim.scheme_data":{"type":"object","description":"DICT-specific output fields on a proxy claim.","required":["claim_id","claimer_tax_identification_number","claimer_owner_type","claimer_opening_date","confirm_reason","cancel_reason","cancelled_by","last_modified"],"properties":{"claim_id":{"type":["string","null"],"description":"BACEN claim ID returned by the DICT provider. Null when `status` is `creation_rejected`.","example":"claim-bacen-uuid-001"},"claimer_tax_identification_number":{"type":"string","description":"Tax identification number (CPF or CNPJ) of the claimer.","example":"12345678901"},"claimer_owner_type":{"type":"string","description":"Whether the claimer is an individual or a legal entity.","enum":["individual","legal_entity"],"example":"individual"},"claimer_opening_date":{"type":["string","null"],"format":"date-time","description":"Date the claimer's account was opened at the claiming institution.","example":"2020-01-01T00:00:00Z"},"confirm_reason":{"type":["string","null"],"description":"Reason the claim was confirmed, if applicable.","enum":["USER_REQUESTED","ACCOUNT_CLOSURE","DEFAULT_OPERATION",null],"example":null},"cancel_reason":{"type":["string","null"],"description":"Reason the claim was cancelled, if applicable.","example":null},"cancelled_by":{"type":["string","null"],"description":"Party that cancelled the claim (`claimer`, `donor`, or `dict`).","example":null},"last_modified":{"type":["string","null"],"format":"date-time","description":"UTC timestamp of the last modification reported by DICT.","example":null}}},"dict_proxy_claim.list_result":{"type":"object","description":"List response for DICT proxy claims. `records` is the page of results,\nordered by `created_at` then `id` descending. To page forward, pass the\nlast record's `id` as `starting_after` on the next request.\n","required":["records"],"properties":{"records":{"type":"array","description":"List of proxy claims matching the query.","items":{"$ref":"#/components/schemas/dict_proxy_claim"}}}}}},"security":[{"sec0":[]}],"paths":{"/proxy_services/dict/proxy_keys":{"post":{"summary":"Create proxy key","description":"Register a proxy key in the DICT directory for a connected account.","operationId":"create-dict-proxy-key","tags":["DICT Proxy Keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_key.creation_details"}}}},"responses":{"200":{"description":"Successfully created proxy key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_key"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"409":{"$ref":"#/components/responses/errors.409.conflict"}}},"get":{"summary":"List proxy keys","description":"List and filter DICT proxy keys.","operationId":"list-dict-proxy-keys","tags":["DICT Proxy Keys"],"parameters":[{"$ref":"#/components/parameters/proxy_keys.list_parameters.limit"},{"$ref":"#/components/parameters/proxy_keys.list_parameters.starting_after"},{"name":"status","in":"query","description":"Filter by proxy key status.","schema":{"type":"string","enum":["active","disabled"]}},{"name":"connected_account_id","in":"query","description":"Filter by connected account ID.","schema":{"type":"string","format":"uuid"}},{"name":"proxy_type","in":"query","description":"Filter by proxy type.","schema":{"type":"string","enum":["phone","email","tax_id","organisation","random_alias"]}},{"name":"proxy_type_code","in":"query","description":"Filter by scheme-specific proxy type code.","schema":{"type":"string","enum":["cpf","cnpj","abn","teli","emal","aubn","orgn","evp"]}},{"name":"proxy_identification","in":"query","description":"Filter by proxy identification value.","schema":{"type":"string"}},{"name":"owner_name","in":"query","description":"Filter by owner name (maximum 140 characters).","schema":{"type":"string","maxLength":140}},{"name":"internal_account_id","in":"query","description":"Filter by internal account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of filtered proxy keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_key.list_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/proxy_services/dict/proxy_keys/{id}":{"get":{"summary":"Get proxy key","description":"Retrieve a single DICT proxy key by its ID.","operationId":"get-dict-proxy-key","tags":["DICT Proxy Keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy key to retrieve.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Proxy key retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_key"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"}}},"post":{"summary":"Update proxy key","description":"Partially update an active DICT proxy key. Only fields present in the\nrequest body are updated; omitted fields are left unchanged.\n\n`owner_name` and `account_identification` changes are forwarded to the\nDICT provider before the record is persisted — a provider failure leaves\nthe key unchanged.\n\nReturns `400` if the key is not currently `active`.\nAn empty request body is valid — the current key is returned with `200`.\n","operationId":"update-dict-proxy-key","tags":["DICT Proxy Keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy key to update.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_key.update_details"}}}},"responses":{"200":{"description":"Proxy key successfully updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_key"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/proxy_services/dict/proxy_keys/{id}/disable":{"post":{"summary":"Disable proxy key","description":"Deregister a proxy key from the DICT directory. The key transitions from\n`active` to `disabled`. The call is idempotent with respect to the\nprovider — if the key is already absent from the directory it is still\nmarked `disabled` in Mambu Payments.\n\nReturns `400` if the key is not currently `active`.\n","operationId":"disable-dict-proxy-key","tags":["DICT Proxy Keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy key to disable.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Proxy key successfully disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_key"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/proxy_services/dict/proxy_keys/{id}/enable":{"post":{"summary":"Enable proxy key","description":"Re-register a previously disabled proxy key in the DICT directory. The\nkey transitions from `disabled` back to `active`. A new\n`directory_entry_id` is issued by the provider and persisted on the key.\n\nReturns `400` if the key is not currently `disabled`.\n","operationId":"enable-dict-proxy-key","tags":["DICT Proxy Keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy key to enable.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Proxy key successfully enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_key"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/proxy_services/dict/proxy_lookups":{"post":{"summary":"Perform proxy lookup","description":"Submit a proxy lookup request against the DICT directory. Returns\nthe created lookup with its current `status`. Owner and account\nfields are populated once `status` reaches `sent`.\n","operationId":"create-dict-proxy-lookup","tags":["DICT Proxy Lookup"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_lookup.creation_details"}}}},"responses":{"200":{"description":"Proxy lookup performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_lookup"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}},"get":{"summary":"List proxy lookups","description":"List and filter past DICT proxy lookups.","operationId":"list-dict-proxy-lookups","tags":["DICT Proxy Lookup"],"parameters":[{"$ref":"#/components/parameters/proxy_lookups.list_parameters.limit"},{"$ref":"#/components/parameters/proxy_lookups.list_parameters.starting_after"},{"name":"status","in":"query","description":"Filter by lookup status.","schema":{"type":"string","enum":["created","processing","sent","completed","rejected"]}},{"name":"connected_account_id","in":"query","description":"Filter by connected account ID.","schema":{"type":"string","format":"uuid"}},{"name":"proxy_type","in":"query","description":"Filter by proxy type.","schema":{"type":"string","enum":["phone","email","tax_id","organisation","random_alias"]}},{"name":"proxy_type_code","in":"query","description":"Filter by scheme-specific proxy type code.","schema":{"type":"string","enum":["cpf","cnpj","abn","teli","emal","aubn","orgn","evp"]}}],"responses":{"200":{"description":"List of filtered proxy lookups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_lookup.list_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/proxy_services/dict/proxy_lookups/{id}":{"get":{"summary":"Retrieve proxy lookup","description":"Returns a single proxy lookup by its ID.","operationId":"get-proxy-lookup","tags":["DICT Proxy Lookup"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy lookup to retrieve.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully retrieved proxy lookup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_lookup"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/proxy_services/dict/proxy_claims":{"post":{"summary":"Create proxy claim","description":"Open a portability or ownership claim for a DICT proxy key registered\nat another institution.\n\n- **Portability** — the same person moves the key to a new institution.\n  The claimer's tax ID must match the donor's.\n- **Ownership** — a new person claims a key (e.g. a reassigned phone\n  number). Tax IDs do not need to match.\n\nEVP (random alias) keys cannot be claimed and will result in a\n`creation_rejected` response.\n\nIf an active claim already exists for the `proxy_identification`, the\nrequest returns `409`.\n","operationId":"create-dict-proxy-claim","tags":["DICT Proxy Claims"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim.creation_details"}}}},"responses":{"200":{"description":"Proxy claim created. `status` is `open` when DICT accepted the claim, or `creation_rejected` when DICT rejected it (e.g. key not found or not claimable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"description":"No proxy configuration found for this legal entity and the DICT scheme."},"409":{"$ref":"#/components/responses/errors.409.conflict"}}},"get":{"summary":"List proxy claims","description":"Returns proxy claims for the authenticated legal entity, with cursor\npagination (`limit`, `starting_after`) and optional filters (`status`,\n`connected_account_id`, `type`, `role`, `proxy_type_code`,\n`proxy_identification`, `internal_account_id`, `proxy_key_id`).\nRecords are ordered by `created_at` descending, then `id` descending.\nTo page forward, pass the last record's `id` as `starting_after` on\nthe next request.\n","operationId":"list-dict-proxy-claims","tags":["DICT Proxy Claims"],"parameters":[{"$ref":"#/components/parameters/proxy_claims.list_parameters.limit"},{"$ref":"#/components/parameters/proxy_claims.list_parameters.starting_after"},{"name":"status","in":"query","required":false,"description":"Filter by claim status.","schema":{"type":"string","enum":["open","creation_rejected"]}},{"name":"connected_account_id","in":"query","required":false,"description":"Filter by connected account ID.","schema":{"type":"string","format":"uuid"}},{"name":"type","in":"query","required":false,"description":"Filter by claim type.","schema":{"type":"string","enum":["ownership","portability"]}},{"name":"role","in":"query","required":false,"description":"Filter by the legal entity's role in the claim. Today all rows have role=claimer; donor-side rows ship with the discovery flow.","schema":{"type":"string","enum":["claimer","donor"]}},{"name":"proxy_type_code","in":"query","required":false,"description":"Filter by scheme-specific proxy type code.","schema":{"type":"string","enum":["cpf","cnpj","abn","teli","emal","aubn","orgn","evp"]}},{"name":"proxy_identification","in":"query","required":false,"description":"Exact-match filter on the proxy identification.","schema":{"type":"string"}},{"name":"internal_account_id","in":"query","required":false,"description":"Filter by internal account linkage.","schema":{"type":"string","format":"uuid"}},{"name":"proxy_key_id","in":"query","required":false,"description":"Filter by the bound local proxy key. Claimer-side rows have a null binding and are not returned by this filter today.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of filtered proxy claims.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim.list_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/proxy_services/dict/proxy_claims/{id}":{"get":{"summary":"Get proxy claim","description":"Retrieve a single DICT proxy claim by its ID.","operationId":"get-dict-proxy-claim","tags":["DICT Proxy Claims"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy claim to retrieve.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Proxy claim retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/proxy_services/dict/proxy_claims/{id}/acknowledge":{"post":{"summary":"Acknowledge proxy claim","description":"Donor acknowledges receipt of an open proxy claim, transitioning it\nfrom `open` to `waiting_resolution`. Only applicable when\n`role = donor` — requests against claimer-side rows return `400`.\n\nThe provider call is synchronous against the simulator; on success\nthe response returns `status = waiting_resolution`. On provider\nrejection the response returns `200` with\n`status = acknowledgment_rejected` and a populated `status_details`\n(rejections are stored business states, not HTTP errors).\n","operationId":"acknowledge-dict-proxy-claim","tags":["DICT Proxy Claims"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy claim to acknowledge.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Proxy claim acknowledged (or acknowledgment rejected by the provider).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/proxy_services/dict/proxy_claims/{id}/confirm":{"post":{"summary":"Confirm proxy claim","description":"Donor confirms a proxy claim in `waiting_resolution`, transitioning it\nto `confirmed` (on provider success) or `confirmation_rejected` (on\nprovider failure). Both outcomes return `200` — rejections are stored\nbusiness states, not HTTP errors.\n\nOn success, if the claim has a bound `proxy_key_id`, the linked proxy\nkey is transitioned from `active` to `disabled` with\n`status_reason = released_via_claim` in the same transaction.\n","operationId":"confirm-dict-proxy-claim","tags":["DICT Proxy Claims"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy claim to confirm.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim.confirm_details"}}}},"responses":{"200":{"description":"Proxy claim confirmed (or confirmation rejected by the provider).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/proxy_services/dict/proxy_claims/{id}/cancel":{"post":{"summary":"Cancel proxy claim","description":"Cancel a proxy claim. Allowed start status depends on the claim `type`:\n- `type=portability` — cancellable from `open` or `waiting_resolution`.\n- `type=ownership` — cancellable from `open`, `waiting_resolution`, or `confirmed`.\n\nEither role (claimer or donor) can call cancel. The\n`scheme_data.cancelled_by` field on the response reflects the row's\n`role` — the side that initiated the cancel.\n\nThe provider call is synchronous against the simulator; on success the\nresponse returns `status = cancelled`. On provider rejection the response\nreturns `200` with `status = cancellation_rejected` and a populated\n`status_details` (rejections are stored business states, not HTTP errors).\n\n**Cancellation does not affect the linked `proxy_key`**: if an ownership\nclaim is cancelled after being confirmed (e.g. DICT `FRAUD`), the\ndonor-side `proxy_key.disabled` state is not auto-reverted. Manual\nreconciliation if needed.\n","operationId":"cancel-dict-proxy-claim","tags":["DICT Proxy Claims"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy claim to cancel.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim.cancel_details"}}}},"responses":{"200":{"description":"Proxy claim cancelled (or cancellation rejected by the provider).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/proxy_services/dict/proxy_claims/{id}/complete":{"post":{"summary":"Complete proxy claim","description":"Complete a proxy claim. Only the claimer side can call this endpoint\n(`role = claimer`). Completion rules depend on the claim `type`:\n- `type=portability` — completable once `status = confirmed`, regardless of deadline.\n- `type=ownership` — completable once `status = confirmed` **and** `completion_period_end` has passed.\n\nOn success the response returns `status = completed` with `proxy_key_id`\npopulated — a new proxy key is created in `active` status. On provider\nrejection the response returns `200` with `status = completion_rejected`\nand a populated `status_details` (rejections are stored business states,\nnot HTTP errors).\n","operationId":"complete-dict-proxy-claim","tags":["DICT Proxy Claims"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID of the proxy claim to complete.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Proxy claim completed (or completion rejected by the provider).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dict_proxy_claim"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}}}}