--- updatedAt: 2026-04-23T18:12:51.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # Get key Searches for a DICT key entry returning the owner information. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Instant payments - Pix management", "description": "API responsible for providing Pix operations (related to DICT) via integrating with external providers", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" }, "version": "0.0.1" }, "servers": [ { "url": "https://sandbox.pismolabs.io/pix-dict", "description": "Sandbox API server for testing." } ], "tags": [ { "name": "Keys", "description": "Manage DICT keys endpoints" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "parameters": { "AuthHeader": { "in": "header", "name": "Authorization", "required": true, "description": "Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.", "schema": { "type": "string", "example": "Bearer eyJhbGci...IUzUx" } } }, "headers": { "XCidResponseHeader": { "description": "Request tracking identifier.", "schema": { "type": "string" } } }, "schemas": { "AccountID": { "type": "string", "description": "Pismo account ID", "example": "8675309" }, "AccountNumber": { "type": "string", "description": "Account number.", "maxLength": 20, "example": "98765432" }, "AccountType": { "type": "string", "enum": [ "CACC", "SLRY", "SVGS", "TRAN" ], "maxLength": 4, "description": "Account type: \n `CACC` - Checking account\n `SVGS` - Savings account\n `TRAN` - Transactional account (Brazil only). Also known as \"conta corrente\" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking. \n `SLRY` - Salary account. Employer deposits a fixed amount every month.\n", "example": "TRAN" }, "Branch": { "type": "string", "description": "Bank-assigned branch ID or ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.", "example": "011" }, "ClaimRequestedDatetime": { "type": "string", "description": "Claim requested date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.", "format": "date-time", "example": "2020-08-13T13:49:03Z" }, "CorrelationID": { "type": "string", "format": "uuid", "description": "The correlation identifier is used to link related API requests and events. The Pismo engineering team can use this to track everything related to a call. If one is not passed, it is automatically generated and returned to the client in a response header.\n", "example": "ea8bc045-9ff7-439f-a318-2e6f974707a5" }, "CreationDatetime": { "type": "string", "description": "Creation datetime. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.", "format": "date-time", "example": "2020-08-13T13:49:03Z" }, "DocumentNumber": { "type": "string", "description": "A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Must be numeric with 11-14 digits.\n", "minLength": 11, "maxLength": 14, "example": "123412341234" }, "Key": { "type": "string", "description": "Value, based on a key's type, used to encrypt Pix key.", "maxLength": 77, "example": "al_fresco@bourdain.com" }, "KeyType": { "type": "string", "description": "User information that can be used to create a Pix key:\n* `CPF` - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number. Similar to a Social Security number in the US. \n* `CNPJ` - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number. Unique ID for legal entities, such as companies and organizations, in Brazil\n* `EMAIL` - Email \n* `PHONE` - Phone number\n* `EVP` - Endereco de pagamento virtual (virtual payment address). A randomly-generated UUID number.\n", "enum": [ "CPF", "CNPJ", "PHONE", "EMAIL", "EVP" ], "example": "EMAIL" }, "message.DetailMessage": { "type": "object", "properties": { "external": { "type": "array", "items": { "$ref": "#/components/schemas/message.ExternalMessage" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/message.ParameterMessage" } }, "payload": { "type": "array", "items": { "$ref": "#/components/schemas/message.PayloadMessage" } } } }, "message.ExternalMessage": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "example": "PBE315" }, "message": { "type": "string", "description": "Error message", "example": "Generic error" } } }, "message.Message": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "example": "EPDA0001" }, "details": { "$ref": "#/components/schemas/message.DetailMessage" }, "message": { "type": "string", "description": "Error message", "example": "User not found" } } }, "message.ParameterMessage": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Parameter in error", "example": "query parameter" }, "message": { "type": "string", "description": "Error message", "example": "Generic error" } } }, "message.PayloadMessage": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Field in error", "example": "Entity.field" }, "message": { "type": "string", "description": "Error messsage", "example": "Generic error" } } }, "OpeningDatetime": { "type": "string", "description": "Opening date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.", "format": "date-time", "example": "2020-08-13T13:49:03Z" }, "OrgID": { "type": "string", "description": "Organization/tenant ID.", "example": "TN-34778262-f4f0-464d-b4c6-a14e2dc6f4be" }, "OwnershipDatetime": { "type": "string", "description": "Ownership date time. A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.", "format": "date-time", "example": "2020-08-13T13:49:03Z" }, "Participant": { "type": "string", "description": "Participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.", "maxLength": 8, "example": "00115678" }, "PersonName": { "type": "string", "description": "Person's name", "maxLength": 100, "example": "Jerry Atrick" }, "PersonType": { "type": "string", "description": "Person type: \n* `LEGAL_PERSON` - An actual person with legal rights\n* `NATURAL_PERSON` - An entity, such as an organization or company.\n", "enum": [ "LEGAL_PERSON", "NATURAL_PERSON" ], "example": "NATURAL_PERSON" }, "presenter.BankAccount": { "type": "object", "required": [ "participant", "account_number", "account_type", "branch", "opening_datetime" ], "properties": { "participant": { "$ref": "#/components/schemas/Participant" }, "account_number": { "$ref": "#/components/schemas/AccountNumber" }, "account_type": { "$ref": "#/components/schemas/AccountType" }, "branch": { "$ref": "#/components/schemas/Branch" }, "opening_datetime": { "$ref": "#/components/schemas/OpeningDatetime" } } }, "presenter.Owner": { "type": "object", "required": [ "document_number", "name", "type" ], "properties": { "document_number": { "$ref": "#/components/schemas/DocumentNumber" }, "name": { "$ref": "#/components/schemas/PersonName" }, "type": { "$ref": "#/components/schemas/PersonType" }, "trade_name": { "$ref": "#/components/schemas/TradeName" } } }, "presenter.SearchRequest": { "type": "object", "required": [ "key" ], "properties": { "key": { "$ref": "#/components/schemas/Key" } } }, "presenter.SearchResponse": { "type": "object", "required": [ "bank_account", "creation_datetime", "key", "key_type" ], "properties": { "org_id": { "$ref": "#/components/schemas/OrgID" }, "account_id": { "$ref": "#/components/schemas/AccountID" }, "key": { "$ref": "#/components/schemas/Key" }, "key_type": { "$ref": "#/components/schemas/KeyType" }, "bank_account": { "$ref": "#/components/schemas/presenter.BankAccount" }, "owner": { "$ref": "#/components/schemas/presenter.Owner" }, "creation_datetime": { "$ref": "#/components/schemas/CreationDatetime" }, "ownership_datetime": { "$ref": "#/components/schemas/OwnershipDatetime" }, "correlation_id": { "$ref": "#/components/schemas/CorrelationID" }, "claim_requested_datetime": { "$ref": "#/components/schemas/ClaimRequestedDatetime" } } }, "TradeName": { "type": "string", "description": "Name under which the business operates. Not necessarily the same as the legal name.", "maxLength": 100, "example": "Acme Widgets" } }, "responses": { "401Unauthorized": { "description": "Unauthorized", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Provider service error": { "value": { "code": "EPDG0013", "message": "Unauthorized access to the provider service" } } } } } }, "403Forbidden": { "description": "Forbidden", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "EPDA0009": { "summary": "Missing required header 'x-tenant'", "value": { "code": "EPDA0009", "message": "Missing required header 'x-tenant'" } }, "EPDA0010": { "summary": "Missing required header 'x-account-id'", "value": { "code": "EPDA0010", "message": "Missing required header 'x-account-id'" } }, "EPDA0152": { "summary": "Missing required param 'id'", "value": { "code": "EPDA0152", "message": "Missing required param 'id'" } } } } } }, "429TooManyRequests": { "description": "Too many requests", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" } } } }, "502BadGateway": { "description": "Bad Gateway", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Provider authentication service error": { "value": { "code": "EPDG0020", "message": "Provider authentication service is unable to complete the request" } } } } } }, "504GatewayTimeout2": { "description": "Gateway Timeout", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Service timeout": { "value": { "code": "EPDA0000", "message": "Timeout while executing the request" } }, "Provider timeout": { "value": { "code": "EPDG0000", "message": "Timeout while executing the request" } } } } } } } }, "security": [ { "BearerAuth": [] } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true }, "paths": { "/v2/pix/keys/search": { "post": { "summary": "Get key", "description": "Searches for a DICT key entry returning the owner information.", "operationId": "post-v2-pix-keys-search", "tags": [ "Keys" ], "parameters": [ { "$ref": "#/components/parameters/AuthHeader" } ], "requestBody": { "description": "Search a key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenter.SearchRequest" }, "examples": { "Searching by CPF key": { "value": { "key": "97361452043" } }, "Searching by CNPJ Key": { "value": { "key": "73901114000186" } }, "Searching by Email Key": { "value": { "key": "email@email.com" } }, "Searching by Phone Key": { "value": { "key": "+5511987654321" } }, "Searching by EVP Key": { "value": { "key": "8d33a43c-0d22-4974-9652-30c80f2d6b0e" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenter.SearchResponse" } } } }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "403": { "$ref": "#/components/responses/403Forbidden" }, "404": { "description": "Resource Not Found", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Provider service error": { "value": { "code": "EPDG0014", "message": "Resource not found on the provider service", "details": { "external": [ { "code": "PBE353", "message": "Entity not found" } ] } } }, "Account not found": { "value": { "code": "EPDA0024", "message": "Account not found for ID {account_id}" } }, "Key not found": { "value": { "code": "EPDA0026", "message": "Key not found" } } } } } }, "409": { "description": "Conflict", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Account blocked cancelled create": { "summary": "Account status blocked or cancelled", "value": { "code": "EPDA0028", "message": "Account status blocked or cancelled" } } } } } }, "429": { "$ref": "#/components/responses/429TooManyRequests" }, "500": { "description": "Internal Server Error", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Provider service communication error": { "value": { "code": "EPDA0029", "message": "Internal errors while attempting to communicate with the provider service" } }, "Invalid client error": { "value": { "code": "EPDG0005", "message": "Invalid Pix provider '{provider_name}'" } }, "Failed marshalling object": { "value": { "code": "EPDG0006", "message": "Failed to marshal JSON object" } }, "Failed unmarshalling object": { "value": { "code": "EPDG0007", "message": "Failed to unmarshal JSON object" } }, "Error reading response data": { "value": { "code": "EPDG0010", "message": "I/O error while reading response data: '{details}'" } }, "Provider service error": { "value": { "code": "EPDG0016", "message": "Provider service returned an internal error while trying to access the resource", "details": { "external": [ { "code": "PBE315", "message": "Generic error" } ] } } } } } } }, "502": { "$ref": "#/components/responses/502BadGateway" }, "503": { "description": "Service Unavailable", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Provider service unavailable": { "value": { "code": "EPDG0017", "message": "Provider service resource is unavailable" } }, "Provider authentication service unavailable": { "value": { "code": "EPDG0021", "message": "Provider authentication service is unavailable" } } } } } }, "504": { "$ref": "#/components/responses/504GatewayTimeout2" } } } } } } ```