--- updatedAt: 2026-04-23T18:12:51.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # Check DICT keys Check that a list of key(s) exist in DICT, a Brazilian national Pix registery and database. Keys can be generated from an email address, a mobile phone number, a Tax ID number, or an EVP (virtual payment address). # 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": { "AccountIDheader": { "in": "header", "name": "x-account-id", "schema": { "type": "string" }, "description": "Pismo account ID", "example": "8675309" }, "CIDheader": { "name": "x-cid", "in": "header", "schema": { "type": "string" }, "description": "The Correlation IDentifier UUID field links related API requests and events. The `x-cid` can help the Pismo engineering team track everything related to a call. If not passed, this field is automatically generated.\n", "example": "B20220921145635222303062944CA66F" }, "OrgIDheader": { "name": "x-tenant", "in": "header", "schema": { "type": "string" }, "description": "Organization/tenant ID", "required": true, "example": "TN-34778262-f4f0-464d-b4c6-a14e2dc6f4be" } }, "headers": { "XCidResponseHeader": { "description": "Request tracking identifier.", "schema": { "type": "string" } } }, "schemas": { "entry.CheckRequest": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/entry.Key" } } } }, "entry.CheckResponse": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/entry.KeyResponse" } } } }, "entry.Key": { "type": "object", "required": [ "key" ], "properties": { "key": { "maxLength": 77, "type": "string", "example": "mason.jarr@example.com" } } }, "entry.KeyResponse": { "type": "object", "properties": { "has_entry": { "type": "boolean", "description": "Does key exist?" }, "key": { "maxLength": 77, "type": "string", "description": "Key value", "example": "nan_obyte@email.com" } } }, "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" } } } }, "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/check": { "post": { "summary": "Check DICT keys", "description": "Check that a list of key(s) exist in DICT, a Brazilian national Pix registery and database. Keys can be generated from an email address, a mobile phone number, a Tax ID number, or an EVP (virtual payment address). \n", "operationId": "post-check-dict-keys", "tags": [ "Keys" ], "parameters": [ { "$ref": "#/components/parameters/OrgIDheader" }, { "$ref": "#/components/parameters/CIDheader" }, { "$ref": "#/components/parameters/AccountIDheader" } ], "requestBody": { "description": "CheckRequest Body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/entry.CheckRequest" } } }, "required": true }, "responses": { "200": { "description": "CheckResponse Body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/entry.CheckResponse" } } } }, "400": { "description": "Bad Request", "headers": { "x-cid": { "$ref": "#/components/headers/XCidResponseHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message.Message" }, "examples": { "Invalid binding": { "value": { "code": "EPDA0002", "message": "Failed to unmarshal request body" } }, "Validate errors": { "value": { "code": "EPDA0003", "message": "There are invalid fields when trying to validate request body", "details": { "payload": [ { "field": "ValidateKeyRequest.key", "message": "Field validation for 'key' failed on the 'oneof' tag" } ] } } } } } } }, "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": "Entry 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" } } } } } } ```