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

# Add a destination

> Adds a way to pay a recipient: a bank account, mobile money wallet and so on, in one currency.

**Build the request from [destination requirements](/api-reference/recipients/get-destination-requirements), not from hardcoded fields.** What a corridor needs differs by country and currency (a sort code in the UK, a routing number and account type in the US, an IBAN in the eurozone).

- `country` is required for every method.
- Where a corridor offers more than one `scheme` (for example `ach` and `wire` in the US), name one.
- Keys containing a dot, such as `bank_address.city`, are parts of one nested field. Send them flat, exactly as listed.
- Where requirements include a bank, pass `bankId` from [List banks](/api-reference/recipients/list-banks) instead of a bank code or name.

Account numbers are not stored by Talescria. Reads return a `last4`, a `label` and, where safe to show in full, a `routing` code.

Requires the `recipients:write` scope.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/recipients/{recipientId}/destinations
openapi: 3.1.0
info:
  title: Talescria API
  version: 1.0.0
  description: >-
    Accounts, recipients, payments, transfers between your accounts, payment
    links, customers and invoices. Authenticate with an access token from your
    OAuth client.
servers:
  - url: https://api.talescria.com
    description: Production (test and live keys)
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Your accounts and their balances.
  - name: Recipients
    description: People and businesses you pay, and where to pay them.
  - name: Payments
    description: Paying recipients, including across currencies.
  - name: Transfers
    description: Moving money between your own accounts.
  - name: Payment links
    description: Links anyone can open to pay you by card.
  - name: Customers
    description: People and businesses who pay you.
  - name: Invoices
    description: One-off invoices and recurring series.
paths:
  /v1/recipients/{recipientId}/destinations:
    post:
      tags:
        - Recipients
      summary: Add a destination
      description: >-
        Adds a way to pay a recipient: a bank account, mobile money wallet and
        so on, in one currency.


        **Build the request from [destination
        requirements](/api-reference/recipients/get-destination-requirements),
        not from hardcoded fields.** What a corridor needs differs by country
        and currency (a sort code in the UK, a routing number and account type
        in the US, an IBAN in the eurozone).


        - `country` is required for every method.

        - Where a corridor offers more than one `scheme` (for example `ach` and
        `wire` in the US), name one.

        - Keys containing a dot, such as `bank_address.city`, are parts of one
        nested field. Send them flat, exactly as listed.

        - Where requirements include a bank, pass `bankId` from [List
        banks](/api-reference/recipients/list-banks) instead of a bank code or
        name.


        Account numbers are not stored by Talescria. Reads return a `last4`, a
        `label` and, where safe to show in full, a `routing` code.


        Requires the `recipients:write` scope.
      operationId: addDestination
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
        - name: recipientId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddDestination'
            examples:
              uk:
                summary: A UK account over Faster Payments
                value:
                  method: bank_transfer
                  currency: GBP
                  country: GB
                  scheme: fps
                  accountHolderName: Ola Nwosu
                  fields:
                    account_number: '12340101'
                    sort_code: 40-12-76
                    bank_name: HSBC
              us:
                summary: >-
                  A US account over ACH, with the bank's address under dotted
                  keys
                value:
                  method: bank_transfer
                  currency: USD
                  country: US
                  scheme: ach
                  accountHolderName: Domestic Ads Limited
                  fields:
                    account_number: '9651242350'
                    routing_number: '101019644'
                    account_type: checking
                    bank_address.line1: 1800 North Pole St.
                    bank_address.city: Orlando
                    bank_address.state_or_province: FL
                    bank_address.postal_code: '32801'
                    bank_address.country: US
                    bank_name: Bank of Nowhere
      responses:
        '201':
          description: Created and attached to the recipient.
          content:
            application/json:
              schema:
                type: object
                properties:
                  destination:
                    $ref: '#/components/schemas/Destination'
        '400':
          description: >-
            `VALIDATION`: A field is missing or malformed. `message` says which.


            `IDEMPOTENCY_KEY_REQUIRED`: This operation needs an
            `Idempotency-Key` header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            `UNAUTHENTICATED`: The access token is missing, expired or revoked.
            Get a new token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `ENVIRONMENT_UNAVAILABLE`: Live mode isn't available until your
            account is approved.


            `INSUFFICIENT_SCOPE`: Your API key lacks the scope this operation
            needs. The scope is named in `message` and the `WWW-Authenticate`
            header.


            `ENVIRONMENT_MISMATCH`: The request named a different environment
            from the key's.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            `NOT_FOUND`: It doesn't exist, or isn't yours. The answer is the
            same for both.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `NOT_VERIFIED`: Your account hasn't finished verification. Finish
            onboarding, then retry.


            `IDEMPOTENCY_IN_PROGRESS`: A request with this `Idempotency-Key` is
            still running. Retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            `UNSUPPORTED`: This can't work as asked, for example an unsupported
            currency, corridor or account. `message` says why.


            `IDEMPOTENCY_KEY_REUSED`: This `Idempotency-Key` was used for a
            different request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`RATE_LIMITED`: Too many requests. Wait for `Retry-After` seconds.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: >-
            `MISCONFIGURED`: Something is wrong on our side. Contact support
            with the `x-request-id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: >-
            `UPSTREAM_ERROR`: A service we depend on answered unexpectedly.
            Retry, and contact support with the `x-request-id` if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '`UPSTREAM_UNAVAILABLE`: Temporarily unavailable. Retry with backoff.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  parameters:
    IdempotencyKeyRequired:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        A unique key for this operation. Send the same key when you retry it.
        Kept for 24 hours.
      schema:
        type: string
        minLength: 8
        maxLength: 255
        pattern: ^[A-Za-z0-9_\-:.]+$
  schemas:
    AddDestination:
      type: object
      required:
        - method
        - currency
        - accountHolderName
        - fields
      properties:
        method:
          type: string
          enum:
            - bank_transfer
            - mobile_money
            - stablecoin
            - internal_transfer
        currency:
          type: string
          description: ISO 4217, or `USDC`. Upper-cased for you.
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2. Required for every rail but `stablecoin`.
        scheme:
          type: string
          description: >-
            The rail. Required where a corridor offers more than one
            (`ach`/`wire`/`rtp` over USD); for a stablecoin destination this is
            the chain. `GET /v1/destination-requirements` lists the choices.
        accountHolderName:
          type: string
          maxLength: 200
          description: Whose name is on the account, which is not always the recipient's.
        bankId:
          type: string
          description: >-
            A bank from `GET /v1/banks`, **instead of** `fields.bank_code`.
            Talescria resolves it and fills whatever the corridor needs, the
            code, and the bank name where the rail demands one, so a form
            offering a picker collects neither. Sending both this and
            `fields.bank_code` is a 422 rather than one silently winning.
          example: bk:NG:058
        fields:
          type: object
          additionalProperties:
            type: string
            maxLength: 200
          description: >-
            The rail's own fields, keyed exactly as `GET
            /v1/destination-requirements` declares them. Open on purpose: a new
            corridor adds keys without a change to this schema.
          example:
            account_number: '12340101'
            sort_code: 40-12-76
            bank_name: HSBC
            bank_address.line1: 1 Example Street
            bank_address.city: London
            bank_address.country: GB
    Destination:
      type: object
      required:
        - id
        - method
        - currency
      properties:
        id:
          type: string
        method:
          type: string
          enum:
            - bank_transfer
            - mobile_money
            - stablecoin
            - internal_transfer
        currency:
          type: string
        scheme:
          type: string
        label:
          type: string
          description: What names the rail to a person, a bank name, or `mpesa`.
          example: HSBC
        last4:
          type: string
          description: >-
            The last four of an account or phone number, or a wallet address
            truncated at both ends. **This is all there is.** The full details
            were sent to the provider and are not stored by Talescria, so there
            is no endpoint that returns them.
          example: '0101'
        routing:
          type: string
          description: >-
            Safe to show in full, because it identifies a bank or branch rather
            than an account, a sort code, a bank code, a BIC.
          example: 40-12-76
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Branch on this, not on `message`. See Errors.
            message:
              type: string
              description: For people. Wording can change.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An access token (`at_test_…` or `at_live_…`) from `POST
        https://idp.talescria.com/oauth/token`.

````

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