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

# Name a number

> Names one of the business's numbers, before its first payment too: a number it already has is renamed as above; a number under one of its number patterns with no account yet gets its account now (201).

**Required permission:** `feature:VIRTUAL_ACCOUNTS`, `virtual-accounts:write`



## OpenAPI

````yaml /api-reference/openapi.json put /v1/virtual-accounts/numbers/{accountNumber}
openapi: 3.0.4
info:
  title: Mesh API
  description: >-
    The bank's developer API. Merchants create and manage customers and verify
    identities.


    **Authentication.** Every call sends `X-Api-Key`, from an IP on that key's
    allowlist. One URL serves both

    modes: an `lsk_test_` key reaches the sandbox, an `lsk_live_` key the bank.


    **Answers.** Every response is `{ success, data, message, request_id }`,
    plus a numeric `code` on failure

    (`13` validation, `14` no key, `15` no permission, `43` feature off,
    `50`-`55` customers; the full list is

    in docs/error-codes.md). Fields are snake_case; empty fields are left out.


    **Creating.** `POST`s that create something need an `Idempotency-Key`
    header. Retrying with the same key

    and body returns the first answer with `Idempotent-Replayed: true`.


    **Lists.** Newest first, at most 100 a page (20 by default). Pass
    `next_cursor` back as `cursor`.
  version: v1
servers:
  - url: https://{host}
    description: 'Your bank''s Mesh URL. One URL serves test and live: the key decides.'
    variables:
      host:
        default: mesh.your-bank.com
        description: Your bank's Mesh host
security:
  - ApiKey: []
tags:
  - name: Status
    description: 'Check a key: its business, mode and permissions.'
  - name: Reference data
    description: Countries and customer types the API accepts.
  - name: Customers
    description: The people a wallet business serves. Needs the wallet product.
  - name: Verifications
    description: 'Identity and business checks: BVN, NIN, CAC, TIN, name enquiry and more.'
  - name: Wallets
    description: 'Accounts that hold money in Purse: the business''s own and its customers''.'
  - name: Virtual accounts
    description: >-
      Numbers your payers pay into: static collection accounts and dynamic
      one-payment accounts.
  - name: Payments
    description: Payments into a virtual account, including held ones.
  - name: Accounts
    description: Balance, history and limits of one account, by its number.
  - name: Business transactions
    description: Every transaction across all your accounts.
  - name: Settlement accounts
    description: Your accounts at the bank, where collections settle.
  - name: Number patterns
    description: Blocks of account numbers the bank gave your business.
  - name: Collection settlements
    description: Payments passed on to your settlement account.
  - name: Charges
    description: What the bank charged you, by service.
  - name: Transfers
    description: Move money between wallets, or out to another bank.
  - name: Settlements
    description: Withdraw to your own bank account.
  - name: Banks
    description: Bank codes for interbank transfers.
  - name: Account names
    description: The name on an account, before you pay it.
  - name: Simulations
    description: 'Test mode only: send a pretend payment into a sandbox account.'
  - name: Events
    description: Poll the events your webhooks carry.
  - name: Webhook endpoint
    description: Where Mesh sends your events, and its signing secret.
  - name: Webhook deliveries
    description: Every delivery attempt, and replays.
paths:
  /v1/virtual-accounts/numbers/{accountNumber}:
    put:
      tags:
        - Virtual accounts
      summary: Name a number
      description: >-
        Names one of the business's numbers, before its first payment too: a
        number it already has is renamed as above; a number under one of its
        number patterns with no account yet gets its account now (201).


        **Required permission:** `feature:VIRTUAL_ACCOUNTS`,
        `virtual-accounts:write`
      parameters:
        - name: accountNumber
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameVirtualAccountRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccountDtoApiResponse'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccountDtoApiResponse'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccountDtoApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorDataApiResponse'
        '401':
          description: Authentication is required
        '403':
          description: The caller lacks permission
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectApiResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectApiResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectApiResponse'
      security:
        - ApiKey: []
components:
  schemas:
    RenameVirtualAccountRequest:
      type: object
      properties:
        first_name:
          type: string
          nullable: true
          example: Adaeze
        middle_name:
          type: string
          nullable: true
          example: Chioma
        last_name:
          type: string
          nullable: true
          example: Okafor
        account_name:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
          example: Lekki branch
      additionalProperties: false
    VirtualAccountDtoApiResponse:
      required:
        - message
        - request_id
        - success
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/VirtualAccountDto'
        message:
          type: string
          nullable: true
        request_id:
          type: string
          nullable: true
          example: 01a1775167aa7693a7acd8df7b596118
        code:
          type: string
          description: >-
            Failures only: the numeric code a client branches on (see
            ErrorCodeNumbers).
          nullable: true
          example: '13'
      additionalProperties: false
    ValidationErrorDataApiResponse:
      required:
        - message
        - request_id
        - success
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/ValidationErrorData'
        message:
          type: string
          nullable: true
        request_id:
          type: string
          nullable: true
          example: 01a1775167aa7693a7acd8df7b596118
        code:
          type: string
          description: >-
            Failures only: the numeric code a client branches on (see
            ErrorCodeNumbers).
          nullable: true
          example: '13'
      additionalProperties: false
    ObjectApiResponse:
      required:
        - message
        - request_id
        - success
      type: object
      properties:
        success:
          type: boolean
        data:
          nullable: true
        message:
          type: string
          nullable: true
        request_id:
          type: string
          nullable: true
          example: 01a1775167aa7693a7acd8df7b596118
        code:
          type: string
          description: >-
            Failures only: the numeric code a client branches on (see
            ErrorCodeNumbers).
          nullable: true
          example: '13'
      additionalProperties: false
    VirtualAccountDto:
      required:
        - account_name
        - account_number
        - created_at
        - fee_bearer
        - id
        - owner_type
        - purpose
        - settles_to
        - status
        - type
      type: object
      properties:
        id:
          type: string
          format: uuid
        account_number:
          type: string
          nullable: true
        account_name:
          type: string
          nullable: true
        name_status:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
          example: static
        purpose:
          type: string
          nullable: true
        owner_type:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
          example: Lekki branch
        status:
          type: string
          nullable: true
        fee_bearer:
          type: string
          nullable: true
          example: business
        settles_to:
          type: string
          nullable: true
        settlement_account:
          $ref: '#/components/schemas/SettlementAccountDto'
        payment_terms:
          $ref: '#/components/schemas/PaymentTermsDto'
        created_at:
          type: string
          format: date-time
      additionalProperties: false
    ValidationErrorData:
      required:
        - fields
      type: object
      properties:
        fields:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          nullable: true
      additionalProperties: false
    SettlementAccountDto:
      required:
        - account_number
        - id
      type: object
      properties:
        id:
          type: string
          format: uuid
        account_number:
          type: string
          nullable: true
        account_name:
          type: string
          nullable: true
      additionalProperties: false
    PaymentTermsDto:
      required:
        - amount_minor
        - charge_minor
        - currency
        - expires_at
        - fee_minor
        - held_payments
        - reference
        - settlement_minor
        - total_payable_minor
        - vat_minor
      type: object
      properties:
        reference:
          type: string
          nullable: true
          example: INV-2026-0042
        currency:
          type: string
          nullable: true
          example: NGN
        amount_minor:
          type: integer
          format: int64
          example: 2500000
        fee_minor:
          type: integer
          format: int64
        vat_minor:
          type: integer
          format: int64
        charge_minor:
          type: integer
          format: int64
        total_payable_minor:
          type: integer
          format: int64
        settlement_minor:
          type: integer
          format: int64
        payer_name:
          type: string
          nullable: true
          example: Adaeze Okafor
        expires_at:
          type: string
          format: date-time
        received_minor:
          type: integer
          format: int64
          nullable: true
        paid_at:
          type: string
          format: date-time
          nullable: true
        transaction_id:
          type: string
          format: uuid
          nullable: true
        held_payments:
          type: integer
          format: int64
        collection_account_id:
          type: string
          format: uuid
          nullable: true
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: apiKey
      description: >-
        An API key: lsk_<test|live>_<public_id>.<secret>. The key also has to be
        used from an address on its allowlist.
      name: X-Api-Key
      in: header

````

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