> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create a Pix key entry > Registers a new Pix key entry in the DICT directory. Assumes Receita Federal validation and MFA ownership authentication were completed by the client before the request. The account resolved from X-Account-Id must accept a new key binding: a salary account (SLRY) is refused with 422 PIX-0176 before any call to the DICT, while keys already bound to a salary account stay valid. After a 502 PIX-0141 or 500 PIX-0000 the outcome is unknown. Repeat the request with the same X-Idempotency and body, only within 30 minutes of the first attempt: the hub resends that attempt's directory request. On the repeat, 201 is the original registration (for an EVP key the returned key is the first attempt's only when the provider had completed that attempt, which the response does not show, so check the account's entries before creating another EVP key). PIX-0102 confirms nothing: the first attempt may still be in progress, or the key is stored but not yet bound to the account (VSync reconciliation); look the key up and, while no entry for the account appears, repeat later with the same X-Idempotency within the window. A classified directory refusal (PIX-0103, PIX-0177, PIX-0178, PIX-0149, PIX-0100 or PIX-0179, below) means the first attempt was refused: fix the cause and use a new X-Idempotency. A repeated 502 PIX-0141 or 500 PIX-0000 is not a refusal: repeat again with the same X-Idempotency within the window, or look the key up. Past the 30 minutes, or under a different X-Idempotency, a repeat is a new directory request, which for an EVP key registers a new key: while the outcome is unknown, check the account's entries instead of creating an EVP key again. An EVP create the hub cannot record for a later repeat is refused with 503 PIX-0032 before any call to the DICT, in a problem+json body (the replay gate's own PIX-0032 uses the legacy envelope): repeat it after a few seconds. The DICT itself can still answer PIX-0102 (the provider already holds or is processing the key; for a key other than EVP repeated after a 502 PIX-0141 or 500 PIX-0000 past the window or under a different X-Idempotency, this usually means that attempt registered it and the entry appears after VSync reconciliation, otherwise look the key up or retry), PIX-0103 (400: its own key limit), PIX-0177 (409: the key belongs to a different person; an OWNERSHIP claim is the usual next step), PIX-0178 (409: the key belongs to the same owner at a different participant; a PORTABILITY claim is the usual next step), PIX-0149 (422: an open claim locks the key), PIX-0100 (422: a CPF/CNPJ key that is not the owner's document) or PIX-0179 (422: a court-order or Pix restriction on the owner or account; do not show its message to end users). PIX-0141 (502) means the adapter call did not complete as a registration: an adapter or provider failure, which may have reached the DICT, or a provider refusal that has no classified code. None of these creates an entry. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-dict.yaml post /entries openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- Public API for Pix keys, claims, fraud markers, infraction reports, and MED funds recovery. license: name: Lerian Studio General License title: Pix Lerian — DICT version: 1.2.0 servers: - url: https://api.example.com/dict-hub/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Manage ownership and portability claims for Pix keys. name: Claims - description: Register, retrieve, list, update, and remove Pix keys. name: Entries - description: Create, query, list, and cancel DICT fraud markers. name: Fraud Markers - description: Manage participant-scoped MED 2.0 funds recoveries. name: Funds Recoveries - description: Manage MED 2.0 infraction reports for the authenticated organization. name: Infraction Reports - description: Look up Pix keys and check whether keys exist in the DICT directory. name: Keys - description: Create, query, cancel, and settle MED 2.0 refunds. name: Refunds - description: >- Read the state of key reconciliation against BACEN, and start a verification or a file reconciliation. name: VSync paths: /entries: post: tags: - Entries summary: Create a Pix key entry description: >- Registers a new Pix key entry in the DICT directory. Assumes Receita Federal validation and MFA ownership authentication were completed by the client before the request. The account resolved from X-Account-Id must accept a new key binding: a salary account (SLRY) is refused with 422 PIX-0176 before any call to the DICT, while keys already bound to a salary account stay valid. After a 502 PIX-0141 or 500 PIX-0000 the outcome is unknown. Repeat the request with the same X-Idempotency and body, only within 30 minutes of the first attempt: the hub resends that attempt's directory request. On the repeat, 201 is the original registration (for an EVP key the returned key is the first attempt's only when the provider had completed that attempt, which the response does not show, so check the account's entries before creating another EVP key). PIX-0102 confirms nothing: the first attempt may still be in progress, or the key is stored but not yet bound to the account (VSync reconciliation); look the key up and, while no entry for the account appears, repeat later with the same X-Idempotency within the window. A classified directory refusal (PIX-0103, PIX-0177, PIX-0178, PIX-0149, PIX-0100 or PIX-0179, below) means the first attempt was refused: fix the cause and use a new X-Idempotency. A repeated 502 PIX-0141 or 500 PIX-0000 is not a refusal: repeat again with the same X-Idempotency within the window, or look the key up. Past the 30 minutes, or under a different X-Idempotency, a repeat is a new directory request, which for an EVP key registers a new key: while the outcome is unknown, check the account's entries instead of creating an EVP key again. An EVP create the hub cannot record for a later repeat is refused with 503 PIX-0032 before any call to the DICT, in a problem+json body (the replay gate's own PIX-0032 uses the legacy envelope): repeat it after a few seconds. The DICT itself can still answer PIX-0102 (the provider already holds or is processing the key; for a key other than EVP repeated after a 502 PIX-0141 or 500 PIX-0000 past the window or under a different X-Idempotency, this usually means that attempt registered it and the entry appears after VSync reconciliation, otherwise look the key up or retry), PIX-0103 (400: its own key limit), PIX-0177 (409: the key belongs to a different person; an OWNERSHIP claim is the usual next step), PIX-0178 (409: the key belongs to the same owner at a different participant; a PORTABILITY claim is the usual next step), PIX-0149 (422: an open claim locks the key), PIX-0100 (422: a CPF/CNPJ key that is not the owner's document) or PIX-0179 (422: a court-order or Pix restriction on the owner or account; do not show its message to end users). PIX-0141 (502) means the adapter call did not complete as a registration: an adapter or provider failure, which may have reached the DICT, or a provider refusal that has no classified code. None of these creates an entry. operationId: createEntry parameters: - description: >- REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Resending the same key and request within 1 hour returns the original response, its status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, path or body, or while the first request runs, is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: 'Reason for creating the entry: USER_REQUESTED or RECONCILIATION' in: header name: X-Reason required: true schema: description: 'Reason for creating the entry: USER_REQUESTED or RECONCILIATION' examples: - USER_REQUESTED type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateEntryBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateEntryOutput' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: >- Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0103). A duplicated or padded X-Account-Id or X-Reason header (PIX-0001). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001, PIX-0010) answer in the legacy {code,title,message} envelope too. '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0102 title: Conflict status: 409 detail: Key value is already registered. code: PIX-0102 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0102, PIX-0177, PIX-0178). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: >- The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json. '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: >- The request body must be sent with Content-Type: application/json. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' description: >- Unprocessable Entity (PIX-0100, PIX-0176, PIX-0179, PIX-0149, PIX-0116). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0140 title: Bad Gateway status: 502 detail: internal error code: PIX-0140 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0140, PIX-0141). '503': content: application/json: schema: $ref: '#/components/schemas/LegacyErrorEnvelope' examples: idempotencyGate: summary: Idempotency gate refusal value: code: PIX-0032 title: Idempotency Unavailable message: >- The request was not processed because the idempotency store is unavailable. Please retry. reconciliationGate: summary: Reconciliation gate refusal value: code: PIX-0119 title: Entry Mutations Temporarily Blocked message: >- Entry mutations for this key type are temporarily blocked while its scope is reconciled (VSync). Retry later. reconciliationGateUnreadable: description: gate unreadable, retry later summary: Gate unreadable value: code: PIX-0183 title: Mutations Temporarily Unavailable message: Mutations are temporarily unavailable. Retry later. application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0032 title: Service Unavailable status: 503 detail: internal error code: PIX-0032 schema: $ref: '#/components/schemas/Detail' description: >- Service Unavailable (PIX-0032). An active VSync reconciliation holds this key type's scope, so the mutation was refused before it ran; retry after the reconciliation ends (PIX-0119). If the gate state cannot be read, the mutation is refused with PIX-0183 before it runs; retry later. Legacy {code,title,message} envelope, NOT problem+json. Replay store unavailable on this fail-closed route, so the mutation was refused rather than executed without replay protection (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: CreateEntryBody: additionalProperties: false properties: keyType: description: Pix key type examples: - CPF type: string keyValue: description: Pix key value examples: - '52998224725' type: string metadata: additionalProperties: {} description: >- Free-form, single-level key/value pairs persisted with the entry. Keys up to 100 characters, values up to 2000 characters, at most 25 entries; nested objects are rejected. examples: - source: mobile maxProperties: 25 type: object required: - keyType type: object CreateEntryOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/EntryAccountOutput' createdAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string holderId: examples: - 019606e5-7f80-9102-3d45-678901234ef0 type: string description: >- CRM holder of the key's account. Absent while a key VSync synchronized from the directory waits for its owner's CRM account. id: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string keyCreationDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyOwnershipDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyType: examples: - CPF type: string keyValue: examples: - '52998224725' type: string metadata: additionalProperties: {} type: object organizationId: examples: - 019606d4-6e7f-8091-2c34-567890123def type: string owner: $ref: '#/components/schemas/EntryOwnerOutput' requestId: examples: - a946d533-7f22-42a5-9a9b-e87cd55c0f4d type: string status: examples: - ACTIVE type: string updatedAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string required: - id - organizationId - keyType - keyValue - status - requestId - keyCreationDate - keyOwnershipDate - account - owner - createdAt - updatedAt type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object EntryAccountOutput: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string openingDate: examples: - '2010-01-10T03:00:00Z' format: date-time type: string participant: examples: - '12345678' type: string type: examples: - CACC type: string required: - branch - number - type - participant type: object EntryOwnerOutput: additionalProperties: false properties: document: examples: - '52998224725' type: string name: examples: - João Silva type: string personType: examples: - NATURAL type: string tradeName: examples: - Silva ME type: string required: - document - personType - name type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.