---
title: "Initiate Payee Creation"
method: POST
path: "/v4/payees"
tags: ["Payee Invitation"]
---

# Initiate Payee Creation

`POST /v4/payees`

Initiate the process of creating 1 to 2000 payees in a batch

Use the batchId in the response to query for status.

In addition to standard semantic validations, a 400 will also result if:

*   there is a duplicate remote id within the batch
*   there is a duplicate email within the batch, i.e. if there is a conflict between the data provided for one payee within the batch and that provided for another payee within the same batch).

The validation at this stage is intra-batch only.

Validation against payees who have already been invited occurs subsequently during processing of the batch.

## Request body

- CreatePayeesRequestV4
  - `payorId` string, required
  - `payees` CreatePayeeV4[], required
    - `email` string, email, required
    - `remoteId` string, required
    - `type` 'Individual' | 'Company', required — The type of the payee
    - `address` CreatePayeeAddressV4, required
      - `line1` string, required
      - `line2` string, nullable
      - `line3` string, nullable
      - `line4` string, nullable
      - `city` string, required
      - `countyOrProvince` string, nullable
      - `zipOrPostcode` string, nullable
      - `country` string, required — Valid ISO 3166 2 character country code. See the <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank" a>ISO specification</a> for details.
    - `paymentChannel` CreatePaymentChannelV4
      - `paymentChannelName` string
      - `iban` string — Must match the regular expression ```^[A-Za-z0-9]+$```.
      - `accountNumber` string — Either routing number and account number or only iban must be set
      - `routingNumber` string — Either routing number and account number or only iban must be set
      - `countryCode` string, required — Valid ISO 3166 2 character country code. See the <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank" a>ISO specification</a> for details.
      - `currency` string, required — Valid ISO 4217 3 letter currency code. See the <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank" a>ISO specification</a> for details.
      - `accountName` string, required
    - `challenge` ChallengeV4 — <p>Used to override the default challenge presented to the payee when they onboard</p> <p>Not used after the payee has onboarded</p>
      - `value` string, required — The value that the user will be asked to verify when they onboard
      - `description` string, required
    - `language` string — An IETF BCP 47 language code which has been configured for use within this Velo environment.<BR> See the /v1/supportedLanguages endpoint to list the available codes for an environment.
    - `company` CompanyV4, nullable
      - `name` string, required
      - `taxId` string, nullable — Company Tax Id must be between 6 and 30 characters long
      - `operatingName` string, nullable
    - `individual` CreateIndividualV4
      - `name` CreateIndividualV3Name, required
        - `title` string
        - `firstName` string, required
        - `otherNames` string
        - `lastName` string, required
      - `nationalIdentification` string
      - `dateOfBirth` string, date, required — Must not be date in future. Example - 1970-05-20

## Response `201`

HTTP Created. Body created only on CSV requests

- CreatePayeesCSVResponseV4
  - `batchId` string, uuid
  - `rejectedCsvRows` CreatePayeesCSVResponseV3RejectedCsvRows[]
    - `lineNumber` integer
    - `rejectedContent` string
    - `message` string

## Other responses

- `400` — Invalid request. See Error message payload for details of failure
- `401` — Invalid access token. May be expired or invalid
- `403` — The authentication does not have permissions to access the resource This usually occurs when there is a valid authentication instance (client or user) but they do not have the required permissions
- `404` — The resource was not found or is no longer available

---

[API](https://skmtc.net/velopaymentsapi/apis/velo-payments-apis.md) · [All operations](https://skmtc.net/velopaymentsapi/apis/velo-payments-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/velopaymentsapi/velo-payments-apis/versions/05c3f09fc50a/schema)