# Add beneficiaries

Create one or more beneficiaries for the logged-in corporate or consumer identity.

Endpoint: POST /beneficiaries
Version: 3.63.5
Security: auth_token, 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.beneficiaryDetails` (any, required)
    The object representing the beneficiary instrument details.

## Response 200 fields (application/json):

  - `operationBatchId` (object, required)

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

  - `operationBatchId.operation` (string, required)
    Describes the operation that has occurred on a beneficiary batch.
    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 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 404 fields (application/json):

  - `code` (string)

  - `message` (string)

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)


## Response 401 fields

## Response 403 fields

## Response 429 fields

## Response 500 fields

## Response 503 fields