> ## 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.

# Create a recipient

> Adds someone you pay. A recipient is who they are (names, email, address); where to send money is added separately as a [destination](/api-reference/recipients/add-a-destination).

- `type: individual` needs `firstName` and `lastName`; `type: business` needs `legalName`. `displayName` is derived from them.
- `relationship` is one of `vendor`, `supplier`, `customer` or `employee`.
- `identification` is optional. A business may only be identified by `business_registration`; an individual by `passport`, `drivers_license` or `national_id`. Document numbers are passed to the payment network and not stored: reads return the type, country and last four.

Your account must be verified first (`409 NOT_VERIFIED` otherwise).

Requires the `recipients:write` scope.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/recipients
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:
    post:
      tags:
        - Recipients
      summary: Create a recipient
      description: >-
        Adds someone you pay. A recipient is who they are (names, email,
        address); where to send money is added separately as a
        [destination](/api-reference/recipients/add-a-destination).


        - `type: individual` needs `firstName` and `lastName`; `type: business`
        needs `legalName`. `displayName` is derived from them.

        - `relationship` is one of `vendor`, `supplier`, `customer` or
        `employee`.

        - `identification` is optional. A business may only be identified by
        `business_registration`; an individual by `passport`, `drivers_license`
        or `national_id`. Document numbers are passed to the payment network and
        not stored: reads return the type, country and last four.


        Your account must be verified first (`409 NOT_VERIFIED` otherwise).


        Requires the `recipients:write` scope.
      operationId: createRecipient
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecipient'
            examples:
              person:
                summary: A contractor paid in GBP
                value:
                  type: individual
                  firstName: Ola
                  lastName: Nwosu
                  relationship: vendor
                  email: ola@nwosu.dev
                  address:
                    line1: 2261 Curtain Road
                    city: London
                    postalCode: EC2A 3AY
                    country: GB
                    stateOrProvince: Greater London
              business:
                summary: A supplier, named by its trading name
                value:
                  type: business
                  legalName: Domestic Ads Limited
                  tradingName: Domestic Ads
                  relationship: supplier
                  email: accounts@domesticads.co
                  address:
                    line1: 14 Broad Street
                    city: Lagos
                    postalCode: '101231'
                    country: NG
                    stateOrProvince: Lagos
      responses:
        '201':
          description: Created. `destinations` is an empty array.
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipient:
                    $ref: '#/components/schemas/Recipient'
        '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'
        '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:
    CreateRecipient:
      type: object
      required:
        - type
        - relationship
        - email
        - address
      properties:
        type:
          type: string
          enum:
            - individual
            - business
          description: Decides which name fields are required.
        firstName:
          type: string
          maxLength: 100
          description: Required for an individual.
        lastName:
          type: string
          maxLength: 100
          description: Required for an individual.
        legalName:
          type: string
          maxLength: 200
          description: Required for a business.
        tradingName:
          type: string
          maxLength: 200
          description: What the business is known as, if that differs from its legal name.
        relationship:
          type: string
          enum:
            - vendor
            - supplier
            - customer
            - employee
          description: >-
            How you're related to the recipient: `vendor`, `supplier`,
            `customer` or `employee`.
        email:
          type: string
          format: email
          maxLength: 320
        phone:
          type: string
          maxLength: 32
        address:
          $ref: '#/components/schemas/RecipientAddress'
        identification:
          type: array
          maxItems: 5
          description: >-
            Identifying documents. A business may only be identified by
            `business_registration`; an individual by `passport`,
            `drivers_license` or `national_id`. The `number` is passed to the
            payment network and not stored by Talescria: reads return the type,
            the issuing country and the last four digits.
          items:
            type: object
            required:
              - type
              - number
              - issuingCountry
            properties:
              type:
                type: string
                enum:
                  - passport
                  - drivers_license
                  - national_id
                  - business_registration
              number:
                type: string
                maxLength: 100
              issuingCountry:
                type: string
                minLength: 2
                maxLength: 2
                description: ISO 3166-1 alpha-2
        nickname:
          type: string
          maxLength: 200
          description: >-
            A label for the recipient at the provider, when their name is not
            what you call them.
    Recipient:
      type: object
      required:
        - id
        - type
        - displayName
        - relationship
        - email
        - address
        - createdAt
      properties:
        id:
          type: string
          example: rcp_9f2c1e4a7b8d4e0f9a1b2c3d4e5f6071
        type:
          type: string
          enum:
            - individual
            - business
        displayName:
          type: string
          description: >-
            What to render. **Derived**, an individual's two names, or a
            business's trading name falling back to its legal name, so it can
            never disagree with the names below. Not accepted as input.
        firstName:
          type: string
        lastName:
          type: string
        legalName:
          type: string
        tradingName:
          type: string
        relationship:
          type: string
          enum:
            - vendor
            - supplier
            - customer
            - employee
          description: How you're related to the recipient.
        email:
          type: string
        phone:
          type: string
        address:
          $ref: '#/components/schemas/RecipientAddress'
        identification:
          type: array
          description: >-
            Which documents identify this recipient, never their numbers. Absent
            means none were given.
          items:
            type: object
            required:
              - type
              - issuingCountry
              - last4
            properties:
              type:
                type: string
                enum:
                  - passport
                  - drivers_license
                  - national_id
                  - business_registration
              issuingCountry:
                type: string
                example: GB
              last4:
                type: string
                description: >-
                  The last four characters of the document number, or the whole
                  thing when it is shorter than four, padding it would invent
                  digits.
                example: '5678'
        createdAt:
          type: integer
          format: int64
          description: Epoch milliseconds.
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/Destination'
    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.
    RecipientAddress:
      type: object
      required:
        - line1
        - city
        - stateOrProvince
        - postalCode
        - country
      properties:
        line1:
          type: string
          maxLength: 200
        line2:
          type: string
          maxLength: 200
        city:
          type: string
          maxLength: 100
        stateOrProvince:
          type: string
          maxLength: 100
          description: >-
            Required. The payment network takes a recipient without one, then
            refuses every payment to them.
        postalCode:
          type: string
          maxLength: 32
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2
    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
  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.