> ## 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. # Claim accounts, charger documents and recurrence charger sides for the calling engine > Each core claims every account it opens, when it opens it, and before its cutover loads the accounts it already holds the same way, in pages of up to 1000 keys. ACCOUNT takes account, plus branch for a current account. A PAYMENT ACCOUNT IS CLAIMED WITHOUT A BRANCH: omit branch or send it empty, never 0, because the Pix rail looks payment accounts up without one, and a payment account claimed with a branch is a key nothing reads. DOCUMENT takes keyValue, a Pix Automático charger's CNPJ. PIX_RECURRENCE_ID_CHARGER takes keyValue, the idRecorrencia of a recurrence whose charger the caller holds: the charger's side, which takes the schedule cancellations the payer's PSP asked for; the payer's side is claimed at PUT /v1/ownership/recurrences/{recurrenceId}. A key the map does not hold is still retained ACCOUNT_UNASSIGNED. 200 answers one result per key, in request order, never repeating the key: CLAIMED, the key is now the caller's; ALREADY_OWNED, it already was and nothing changed; HELD_ELSEWHERE, the JDC-0102 fact: another engine holds the key, so report it to an operator, because only an operator moves a key; INVALID, the JDC-0104 fact: the key is not usable and nothing was written for it. One key's outcome never fails another. 422 JDC-0002: no key, or more than 1000. 422 JDC-0104: a key carries bytes that are not valid UTF-8, and the whole call is refused. 503, a dropped connection or a timeout: the call may have stopped part-way and some keys may be recorded; send the same call again, it is idempotent. The owner is always the caller. ## OpenAPI ````yaml /pt/openapi/v3-current/jd-courier.yaml post /v1/ownership/claims openapi: 3.1.0 info: contact: email: support@lerian.studio name: Lerian Studio Support description: >- The JD Courier API. Operators use it to manage the engines, the ownership map, the rails and their delivery modes, the retained messages, the SPB send journal and reconciliation. Engines use it to resolve and claim ownership, declare their Pix Automático payment legs, and relay a payment between two cores of the same institution to the core that owns the payee account. license: name: Lerian Studio General License title: JD Courier API version: v1.0.0 servers: [] security: - BearerAuth: [] tags: - description: >- The engine registry: the cores that consume the JD channel through the Courier, each with its participant set name: Engines - description: 'The ownership map: which engine owns each key. Every change is audited.' name: ownership - description: >- The rails: what each declares about itself, its activation and state per tenant, and its delivery modes name: channels - description: >- The engines' side of the ownership map: resolution for the on-us gate, authoritative and never advisory, the claim of the accounts, charger documents and Pix Automático recurrences the engine holds, and the declaration of a payment leg it holds. name: ownership-query - description: >- A same-bank Pix or TED between two cores: the Courier asks the map who owns the payee account, forwards the body byte for byte to that engine's address for the rail, and relays its answer. It stores, retries and posts nothing; bodies are not modelled. name: cross-core - description: >- The durable message store: redelivery on demand, without asking the vendor again name: ledger - description: >- Count reconciliation per rail: E(m) = C(m) + T(m) + R(m), the sequence gaps it saw, and the sends whose return leg never arrived name: assurance - description: >- The SPB send journal: every send, written before it leaves, and the sends whose outcome is unknown. A by-hand close records an operator's finding and never resends. name: send-journal - description: >- Per-(tenant, channel) state an operator acts on: lifting a durable channel halt name: channel-leases - description: >- Messages the Courier holds because no engine could receive them. A routing or delivery retention leaves by itself once its cause lifts, or when an operator asks for its routing decision to be run again. name: retained paths: /v1/ownership/claims: post: tags: - ownership-query summary: >- Claim accounts, charger documents and recurrence charger sides for the calling engine description: >- Each core claims every account it opens, when it opens it, and before its cutover loads the accounts it already holds the same way, in pages of up to 1000 keys. ACCOUNT takes account, plus branch for a current account. A PAYMENT ACCOUNT IS CLAIMED WITHOUT A BRANCH: omit branch or send it empty, never 0, because the Pix rail looks payment accounts up without one, and a payment account claimed with a branch is a key nothing reads. DOCUMENT takes keyValue, a Pix Automático charger's CNPJ. PIX_RECURRENCE_ID_CHARGER takes keyValue, the idRecorrencia of a recurrence whose charger the caller holds: the charger's side, which takes the schedule cancellations the payer's PSP asked for; the payer's side is claimed at PUT /v1/ownership/recurrences/{recurrenceId}. A key the map does not hold is still retained ACCOUNT_UNASSIGNED. 200 answers one result per key, in request order, never repeating the key: CLAIMED, the key is now the caller's; ALREADY_OWNED, it already was and nothing changed; HELD_ELSEWHERE, the JDC-0102 fact: another engine holds the key, so report it to an operator, because only an operator moves a key; INVALID, the JDC-0104 fact: the key is not usable and nothing was written for it. One key's outcome never fails another. 422 JDC-0002: no key, or more than 1000. 422 JDC-0104: a key carries bytes that are not valid UTF-8, and the whole call is refused. 503, a dropped connection or a timeout: the call may have stopped part-way and some keys may be recorded; send the same call again, it is idempotent. The owner is always the caller. operationId: claimOwnershipKeys requestBody: content: application/json: schema: $ref: '#/components/schemas/ClaimOwnershipKeysRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/OwnershipClaimReport' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unauthorized '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Service Unavailable security: - engineCredentials: - ownership:write components: schemas: ClaimOwnershipKeysRequest: additionalProperties: false properties: keys: items: $ref: '#/components/schemas/OwnershipClaimKey' maxItems: 1000 minItems: 1 type: - array - 'null' required: - keys type: object OwnershipClaimReport: additionalProperties: false properties: results: items: $ref: '#/components/schemas/OwnershipClaimResult' type: - array - 'null' required: - results 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 OwnershipClaimKey: additionalProperties: false properties: account: description: >- ACCOUNT only: the account number, digits with an optional trailing check-digit letter. maxLength: 256 type: string branch: description: >- ACCOUNT only: a current account's branch, 1 to 4 digits. A payment account is claimed WITHOUT a branch: omit it or send it empty, never 0. maxLength: 256 type: string keyKind: enum: - ACCOUNT - DOCUMENT - PIX_RECURRENCE_ID_CHARGER type: string keyValue: description: >- DOCUMENT: a Pix Automático charger's CNPJ. PIX_RECURRENCE_ID_CHARGER: the idRecorrencia of a recurrence whose charger the engine holds. As held; do not pre-normalize. maxLength: 256 type: string required: - keyKind type: object OwnershipClaimResult: additionalProperties: false properties: outcome: enum: - CLAIMED - ALREADY_OWNED - HELD_ELSEWHERE - INVALID type: string required: - outcome 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 engineCredentials: description: >- An Access Manager application token whose subject is bound to exactly one engine; an engine may hold several, one per calling product. It reaches only the operations its scopes name; the operator surface refuses it. flows: clientCredentials: scopes: cross-core:send: Send a same-bank payment to the core that owns the payee account ownership:read: Read the ownership map ownership:write: >- Claim accounts, charger documents or a Pix Automático recurrence, or declare a Pix Automático payment leg, for the calling engine alone tokenUrl: https://access-manager.example.com/v1/login/oauth/access_token type: oauth2 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.