> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panoqore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bind a named account

> The tenant supplies a number it opened with its partner. In FULL mode PanoQore first checks with the partner that the number is an open account under the tenant's credentials, and takes the name from it.

**Scope:** `named:write`.



## OpenAPI

````yaml /openapi.json post /v1/accounts/{account_id}/named-accounts:bind
openapi: 3.0.3
info:
  title: PanoQore API
  version: v1
  description: >-
    The REST form of the panoqore.v1 contract, limited to what an API key can
    call. Generated from the contract: do not edit by hand.


    Bodies are JSON in lowerCamelCase. A field at its zero value (empty string,
    `0`, `false`, empty list) is left out of responses. 64-bit integers and
    money are strings.
servers:
  - url: https://api.panoqore.example
    description: 'Live. PLACEHOLDER: the production host has not been set'
  - url: https://api.sandbox.panoqore.example
    description: 'Sandbox. PLACEHOLDER: the sandbox host has not been set'
  - url: http://localhost:8080
    description: A server on your own machine
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Accounts, their balances and their history.
  - name: Entries
    description: 'Balanced journal entries: post, hold pending, reverse.'
  - name: Holds
    description: Reservations on an account with no counterparty yet.
  - name: Named accounts
    description: >-
      Partner account numbers bound to wallets, and the credits reported to
      them.
  - name: Lending
    description: >-
      Lending turns loan events into balanced entries on the Lending module's
      accounts. PanoQore holds no loan terms: schedules, interest, allocation
      and credit decisions stay with the product, which tells the ledger what
      happened. Loans are told apart by the product's loan_ref, which is opaque
      and carries no PII.
  - name: Fees
    description: >-
      Fees charges a tenant's schedules as extra postings. A schedule applies
      only to an entry that names it in fee_schedule: the first debit leg pays,
      and the fee is credited to the schedule's income account.
  - name: FX
    description: Rates, quotes and conversions.
  - name: Reconciliation
    description: Partner statements, breaks and the daily control.
  - name: Reporting
    description: Periods, exports and the trial balance.
  - name: Webhooks
    description: >-
      Outbound webhooks: the same CloudEvents the event stream shows, posted to
      a tenant's HTTPS endpoints. Each delivery carries Qore-Signature: t=<unix
      seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">, made with the endpoint's
      signing secret. A delivery that is not answered 2xx within 10 seconds is
      retried: eight tries over 24 hours, then it waits for a replay. Delivery
      is at least once; drop duplicates by the event id. Managing endpoints
      needs the manage scope (tenant admins) or webhooks:manage (an API key).
  - name: Approvals
    description: >-
      Maker-checker for every change to money. One workflow for adjustments,
      reversals, freezes, limit changes, FX rates, integration-mode changes,
      named-account changes and live API keys.
  - name: Events
    description: >-
      The append-only, hash-chained event log. The same rows feed Kafka through
      the outbox.
  - name: Chart of accounts
    description: >-
      The tenant's chart of accounts: one ledger per currency or token, built
      from account modules, with internal accounts created from templates.
      Customer wallets are opened through Ledger.CreateAccount.
  - name: Tenant
    description: The tenant and what it is connected to.
  - name: Identity
    description: Who a credential is.
paths:
  /v1/accounts/{account_id}/named-accounts:bind:
    post:
      tags:
        - Named accounts
      summary: Bind a named account
      description: >-
        The tenant supplies a number it opened with its partner. In FULL mode
        PanoQore first checks with the partner that the number is an open
        account under the tenant's credentials, and takes the name from it.


        **Scope:** `named:write`.
      operationId: NamedAccounts_Bind
      parameters:
        - name: account_id
          in: path
          required: true
          description: The account id.
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Your unique key for this write, at most 255 characters. A retry with
            the same key and body gets the first answer back.
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                partner:
                  type: string
                  example: safehaven
                accountNumber:
                  type: string
                  example: '0123456789'
                bankCode:
                  type: string
                accountName:
                  type: string
                mandateRef:
                  type: string
              required:
                - partner
                - accountNumber
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedAccount'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
components:
  schemas:
    NamedAccount:
      type: object
      properties:
        id:
          type: string
          description: nam_…
        accountId:
          type: string
        accountLabel:
          type: string
          description: the bound ledger account's name
        partner:
          type: string
          description: safehaven | nomba | …
        partnerName:
          type: string
        accountNumber:
          type: string
        bankCode:
          type: string
        accountName:
          type: string
        currency:
          type: string
        status:
          $ref: '#/components/schemas/NamedAccountStatus'
        mandateRef:
          type: string
        partnerRef:
          type: string
        failureReason:
          type: string
        pendingApprovalId:
          type: string
        issuedAt:
          type: string
          format: date-time
        closedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    NamedAccountStatus:
      type: string
      enum:
        - PENDING
        - ACTIVE
        - FROZEN
        - CLOSED
        - FAILED
      description: '`PENDING`: asked the partner, no number yet'
    Error:
      type: object
      description: Every refusal on a `/v1` path has this shape. Branch on `error.code`.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - details
          properties:
            code:
              type: string
              description: Stable and safe to branch on.
              example: INSUFFICIENT_FUNDS
            message:
              type: string
              description: For people. It can change.
            details:
              type: object
              additionalProperties:
                type: string
              description: Context for this code. Empty when there is none.
            request_id:
              type: string
              description: >-
                Quote it when you ask about a failure. Absent on
                `INVALID_REQUEST`, which is refused before a handler runs.
  responses:
    Error:
      description: Refused. See `error.code`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key, `pk_live_…` or `pk_test_…`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.