# Add payees

Payees (previously "beneficiaries"). Create one or more payees for the logged-in corporate or consumer identity.

Endpoint: POST /beneficiaries
Version: v3
Security: auth_token, api-key

## Security:

  - `auth_token` (unknown)
    http bearer JWT

  - `api-key` (unknown)
    apiKey in header api-key

## Header parameters:

  - `idempotency-ref` (string)
    A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

## Request fields (application/json):

  - `tag` (string)
    The tag field is a custom field that can be used to search and filter.

  - `beneficiaries` (array, required)
    The object representing the beneficiaries' details.

  - `beneficiaries.trustLevel` (string, required)
    The value that determines whether a Beneficiary is trusted or not.
    Enum: "TRUSTED"

  - `beneficiaries.externalRefs` (array)
    The id of the entity as it is represented on the caller system.

  - `beneficiaries.group` (string)
    A custom field that can be used to categorise a beneficiary for easier searching and filtering.

  - `beneficiaries.beneficiaryInformation` (any, required)
    The object representing the beneficiary details.

  - `beneficiaries.beneficiaryInformation.businessName` (string, required)
    The business beneficiary name. The allowed length and pattern is dependent on the beneficiary details type:
`InstrumentDetailsBeneficiary` or `BankAccountDetailsBeneficiary` with `IBANDetails`: >= `1` character and <= `150` characters
`BankAccountDetailsBeneficiary` with `FasterPaymentsBankDetailsOrBACSBankDetails`: >= `1` character and <= `140` characters with a pattern of `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;\{@\r\n]*$`
(please note that the `’` symbol is the unicode value U+2019 (right single quotation mark) and not the unicode value U+0027 (apostrophe))

  - `beneficiaries.beneficiaryInformation.nationality` (string)
    The nationality of the consumer. Must be a valid ISO 3166-1 alpha-2 country code (e.g., 'GB', 'FR').

  - `beneficiaries.beneficiaryInformation.dateOfBirth` (string)
    The date of birth of the consumer. Must be a valid date in ISO 8601 format (YYYY-MM-DD) and should not be a future date.

  - `beneficiaries.beneficiaryInformation.fullName` (string, required)
    The person beneficiary name. The allowed length and pattern is dependent on the beneficiary details type:
`InstrumentDetailsBeneficiary` or `BankAccountDetailsBeneficiary` with `IBANDetails`: >= `1` character and <= `150` characters
`BankAccountDetailsBeneficiary` with `FasterPaymentsBankDetailsOrBACSBankDetails`: >= `1` character and <= `140` characters with a pattern of `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;\{@\r\n]*$`
(please note that the `’` symbol is the unicode value U+2019 (right single quotation mark) and not the unicode value U+0027 (apostrophe))

  - `beneficiaries.beneficiaryDetails` (any, required)
    The object representing the beneficiary instrument details.

  - `beneficiaries.beneficiaryDetails.instrument` (object, required)

  - `beneficiaries.beneficiaryDetails.instrument.id` (string, required)

  - `beneficiaries.beneficiaryDetails.instrument.type` (string, required)
    Enum: "managed_cards", "managed_accounts"

  - `beneficiaries.beneficiaryDetails.address` (string)
    **Deprecated** — use `postalAddress` instead. This field is passed to the
provider as unstructured address lines and cannot carry a town name or country
code, which some payment schemes require.
The beneficiary's address.

  - `beneficiaries.beneficiaryDetails.postalAddress` (object)
    The beneficiary's address in structured form.

  - `beneficiaries.beneficiaryDetails.postalAddress.line1` (string)
    The primary line of the beneficiary's address — the street name, building
number and postal code.

  - `beneficiaries.beneficiaryDetails.postalAddress.line2` (string)
    Additional address information — the building name, floor, room, department
or other location details.

  - `beneficiaries.beneficiaryDetails.postalAddress.townName` (string)
    The town or city of the beneficiary's address. It cannot be derived from the
address lines, so send it here rather than inside `line1` or `line2`.

  - `beneficiaries.beneficiaryDetails.postalAddress.countryCode` (string)
    The country of the beneficiary's address in ISO 3166 alpha-2 format. It cannot
be derived from the address lines, so send it here rather than inside `line1`
or `line2`.

  - `beneficiaries.beneficiaryDetails.bankName` (string)
    The beneficiary's bank name.

  - `beneficiaries.beneficiaryDetails.bankAddress` (string)
    The beneficiary's bank address.

  - `beneficiaries.beneficiaryDetails.bankCountry` (string)
    The beneficiary's bank country in ISO 3166 alpha-2 format.

  - `beneficiaries.beneficiaryDetails.bankAccountDetails` (any, required)
    Details of the beneficiary bank account, depending on the type of transfer chosen.

  - `beneficiaries.beneficiaryDetails.bankAccountDetails.iban` (string, required)
    International Bank Account Number, required for wire transfer over SEPA or RIX

  - `beneficiaries.beneficiaryDetails.bankAccountDetails.bankIdentifierCode` (string)
    BIC, for wire transfer over SEPA or RIX

  - `beneficiaries.beneficiaryDetails.bankAccountDetails.accountNumber` (string, required)
    Account number, required for wire transfer over Faster Payments.

  - `beneficiaries.beneficiaryDetails.bankAccountDetails.sortCode` (string, required)
    Sort code, required for wire transfer over Faster Payments.

  - `beneficiaries.beneficiaryDetails.bankAccountDetails.secondaryReference` (string)

## Response 200:

  - `200` (unknown)
    Success

## Response 200 fields (application/json):

  - `operationBatchId` (object, required)

  - `operationBatchId.batchId` (string, required)
    The unique identifier of a Beneficiary.

  - `operationBatchId.operation` (string, required)
    Enum: "CREATE", "REMOVE"

  - `tag` (string)
    The tag field is a custom field that can be used to search and filter.

  - `state` (string, required)
    Enum: "INITIALISED", "FAILED", "PENDING_CHALLENGE", "CHALLENGE_FAILED", "CHALLENGE_COMPLETED", "COMPLETED"

## Response 200 headers (application/json):

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 400:

  - `400` (unknown)
    Bad Request Error - Your request is invalid.

## Response 400 fields (application/json):

  - `message` (string)
    When present helps to identify and fix the problem.

  - `syntaxErrors` (object)
    Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.

  - `syntaxErrors.invalidFields` (array)

  - `syntaxErrors.invalidFields.params` (array)

  - `syntaxErrors.invalidFields.fieldName` (string)

  - `syntaxErrors.invalidFields.error` (string)
    Enum: "REQUIRED", "HAS_TEXT", "REQUIRES", "SIZE", "RANGE", "IN", "NOT_IN", "REGEX", "EXACTLY", "AT_LEAST", "AT_MOST", "ALL_OR_NONE"

## Response 400 headers (application/json):

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 401:

  - `401` (unknown)
    Unauthorized - Your credentials or access token are invalid.

## Response 401 headers:

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 403:

  - `403` (unknown)
    Forbidden - Access to the requested resource or action is forbidden.

## Response 403 fields (application/json):

  - `errorCode` (string)
    Enum: "INSUFFICIENT_PERMISSIONS"

## Response 403 headers (application/json):

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 404:

  - `404` (unknown)
    Not found - The requested resource couldn't be found.

## Response 404 fields (application/json):

  - `code` (string)

  - `message` (string)

## Response 404 headers (application/json):

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 429:

  - `429` (unknown)
    Too many requests.

## Response 429 headers:

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

  - `x-ratelimit-limit` (string, required)
    Example: `20, 10;w=60, 20;w=3600, 200;w=86400`
The first number (20) is the limit that has been exceeded.
The remaining numbers are the limits that are in force, with 'w' meaning 'window in seconds'. In this example `20;w=3600` was exceeded. 20 calls in 3600secs (1hr)

  - `x-ratelimit-reset` (integer, required)
    The number of seconds until the window is reset.

## Response 500:

  - `500` (unknown)
    Internal Server Error - There is a problem with the server. Please try again later.

## Response 500 headers:

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 503:

  - `503` (unknown)
    Service Unavailable - The requested service is temporarily unavailable. Please try again later.

## Response 503 headers:

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response default:

  - `default` (unknown)
    Error

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)