# Beneficiary batch

Notification that a Beneficiary batch has been submitted.

Endpoint: POST /beneficiaries/batch/watch
Version: v2

## Header parameters:

  - `call-ref` (string)
    A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

  - `published-timestamp` (integer, required)
    The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

  - `signature` (string, required)
    The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the `published-timestamp` using your API key.

  - `signature-v2` (string, required)
    The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the `call-ref + payload + published-timestamp` using your API key.

## Request fields (application/json):

  - `id` (string, required)

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

  - `tag` (string)

  - `publishedTimestamp` (string, required)
    Epoch timestamp using millisecond precision.

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

  - `beneficiaries` (array, required)

  - `beneficiaries.id` (string, required)

  - `beneficiaries.externalRefs` (array)

  - `beneficiaries.group` (string)

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

  - `beneficiaries.beneficiaryInformation` (object, required)

  - `beneficiaries.beneficiaryInformation.businessBeneficiaryType` (object)

  - `beneficiaries.beneficiaryInformation.businessBeneficiaryType.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.consumerBeneficiaryType` (object)

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

  - `beneficiaries.beneficiaryInformation.consumerBeneficiaryType.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.consumerBeneficiaryType.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` (object, required)

  - `beneficiaries.beneficiaryDetails.instrumentDetailsBeneficiary` (object)
    Represents a Weavr beneficiary instrument typically used in Send transactions.

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

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

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

  - `beneficiaries.beneficiaryDetails.bankAccountDetailsBeneficiary` (object)

  - `beneficiaries.beneficiaryDetails.bankAccountDetailsBeneficiary.beneficiaryName` (string)
    The name of the beneficiary

  - `beneficiaries.beneficiaryDetails.bankAccountDetailsBeneficiary.address` (string)
    The beneficiary address

  - `beneficiaries.beneficiaryDetails.bankAccountDetailsBeneficiary.bankName` (string)
    The name of the beneficiary bank

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

  - `beneficiaries.beneficiaryDetails.bankAccountDetailsBeneficiary.bankCountry` (string)
    The beneficiary bank country - using ISO 3166 alpha-2

  - `beneficiaries.beneficiaryDetails.bankAccountDetailsBeneficiary.sepaBankDetails` (object)
    Bank details used in case the wire transfer is executed over SEPA or RIX

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

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

  - `beneficiaries.beneficiaryDetails.bankAccountDetailsBeneficiary.fasterPaymentsBankDetails` (object)
    Bank details used in case the wire transfer is executed over Faster Payments.

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

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

  - `beneficiaries.beneficiaryDetails.bankAccountDetailsBeneficiary.fasterPaymentsBankDetails.secondaryReference` (string)

  - `beneficiaries.state` (string, required)
    Enum: "INITIALISED", "INVALID", "PENDING_CHALLENGE", "CHALLENGE_FAILED", "ACTIVE", "REMOVED"

  - `beneficiaries.validationFailure` (string)
    Enum: "INSTRUMENT_DETAILS_NOT_FOUND", "BENEFICIARY_DETAILS_ALREADY_EXIST", "BENEFICIARY_BELONGS_TO_SAME_IDENTITY", "BENEFICIARY_VALIDATION_FAILURE_UNKNOWN"