> ## Documentation Index > Fetch the complete documentation index at: https://docs.ebury.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit a Mass Beneficiary instruction Submit a new mass beneficiary instruction that can be processed in async or sync mode. ## OpenAPI ````yaml /openapi.json post /mass-beneficiaries openapi: 3.0.0 info: description: | Ebury API allows customers: to retrieve accounts, balances, beneficiaries, and transactions; to get buy/sell estimates and quotes, book trades and retrieve trade history; to allocate payments to a trade and beneficiary, and to submit payments in bulk; to download documents such as trade receipt, payment instruction and payment receipt; to manage the authorised persons on their account. The Metadata API allows applications to clarify some parts of the Ebury API that are impractical to express schematically. termsOfService: https://docs.ebury.io/#terms-of-use title: Ebury API version: '0.1' servers: - url: https://{environment}.ebury.io variables: environment: default: api enum: - api - sandbox security: - api_key: [] paths: /mass-beneficiaries: post: tags: - Mass Beneficiaries summary: Submit a Mass Beneficiary instruction description: >- Submit a new mass beneficiary instruction that can be processed in async or sync mode parameters: - description: The ID of the client in: query name: client_id required: true schema: type: string - name: Authorization in: header description: The access token required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/NewMassBeneficiaryList' description: The list of beneficiaries to submit required: true responses: '202': description: Mass beneficiary request accepted, see response body for status content: application/json: schema: $ref: '#/components/schemas/MassBeneficiary' '400': description: >- Formatting or schema validation error. See error message for further details content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '401': description: Access denied due to authentication failure '403': description: >- Could not complete action due to data constraints. Refer to error message for additional details content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '404': description: Client ID not found '502': description: Internal integration error. Contact support content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' components: schemas: NewMassBeneficiaryList: description: >- A list of beneficiaries to be created via the Mass Beneficiaries service. items: $ref: '#/components/schemas/NewBeneficiary' type: array MassBeneficiary: description: A representation of a mass beneficiary. properties: mass_beneficiary_id: description: Unique UUID of the mass beneficiary type: string format: uuid error: $ref: '#/components/schemas/ErrorMessage' links: $ref: '#/components/schemas/LinksMassBeneficiary' summary: $ref: '#/components/schemas/MassBeneficiarySummary' status: $ref: '#/components/schemas/EnumMassBeneficiaryStatus' type: object ErrorMessage: description: An error message. properties: code: type: string description: The code for the error. details: description: Error details type: string message: type: string description: A short description of the cause of the error. required: - code - message - details type: object NewBeneficiary: allOf: - $ref: '#/components/schemas/BankAccountCoreData' - $ref: '#/components/schemas/BeneficiaryCoreData' description: The data to create a new beneficiary. required: - country_code - name - email_notification type: object LinksMassBeneficiary: description: >- Links for the mass beneficiary related information. Each link helps the user agent to fetch resources related to errored beneficiaries, and also those created successfully. The mass_beneficiary_id does not need to be stored as the said resources may be accessed with the provided links. properties: errors_href: description: The link to the errors endpoint type: string created_href: description: The link to the result endpoint type: string type: object MassBeneficiarySummary: description: Categorized counters for the mass beneficiary. properties: received: description: Total count of received beneficiaries type: number created: description: Total count of created beneficiaries type: number errored: description: Total count of errored beneficiaries type: number type: object EnumMassBeneficiaryStatus: description: >- This is an enumeration of the status of every mass beneficiary instruction enum: - pending - creating - created - failed - unknown type: string BankAccountCoreData: description: >- The data of the bank account. Refer to the Metadata API for valid field combinations. properties: account_number: description: The account number of the bank account. type: string bank_address_line_1: description: The first address line of the bank. type: string bank_country_code: description: The ISO 3166-1 alpha-2 code of the bank's country. pattern: '[A-Z]{2}' type: string bank_currency_code: description: The ISO 4217 code of the bank account's currency. pattern: '[A-Z]{3}' type: string bank_identifier: description: The identifier of the bank. type: string bank_name: description: Name of the bank account holder. type: string correspondent_account: description: The account for the correspondant account of the bank. type: string correspondent_swift_code: description: The SWIFT code for the correspondant account of the bank. type: string iban: description: The IBAN of the bank account. type: string inn: description: The INN of the bank account. type: string kbk: description: The KBK of the bank account. type: string kio: description: The KIO of the bank account. type: string kpp: description: The KPP of the bank account. type: string purpose_of_payment: description: >- Text explaining the purpose of payment. Required by the Central Bank for all payments sent to China (CHN) in the Chinese Renminbi (CNY) currency or United Arab Emirates in any currency (GDE to RDA) [Coming soon]. enum: - /CGODDR/ - /CGODDR/PART/ - /CGODDR/RETN/ - /CSTRDR/ - /CSTRDR/PART/ - /CSTRDR/RETN/ - /COCADR/ - /COCADR/RTN/ - /CCTFDR/ - /CCTFDR/PART/ - /CCTFDR/RETN/ - /CCDNDR/ - /CCDNDR/RTN/ - GDE - GDI - GMS - STS - ATS - OTS - STR - SCO - INS - FIS - IPC - TCS - ITS - IFS - RDS - PMS - TTS - PRS - GOS - SAL - IGD - IID - PIP - PRR - DOE - ISH - ISL - ISS - IOL - IOD - GRI - CHC - EDU - ALW - AES - LAS - OVT - TKT - SAA - COP - COM - EOS - BON - PEN - UTL - DCP - LND - LIP - IPO - POR - RNT - LNC - EMI - DIV - ACM - CCP - POS - MCR - CIN - TOF - IGT - OAT - SVI - SVO - SVP - MWI - MWO - MWP - PRP - PRW - IRP - IRW - CEA - PPA - DSF - DLF - FSA - FIA - DSA - DLA - FDA - AFA - SLA - LLA - LEA - RFS - TCR - CEL - PPL - LDS - LDL - FSL - FIL - DSL - DLL - FDL - AFL - SLL - LLL - LEL - RLS - TCP - TAX - REL - RDL - REA - RDA type: string reason_for_trade: description: The reason for trade of the bank account. type: string reference_information: description: The reference information of the bank account. type: string russian_central_bank_account: description: The Russian central account number of the bank account. type: string swift_code: description: The SWIFT code of the bank account. type: string vo: description: The VO of the bank account. type: string required: - bank_country_code - bank_currency_code type: object BeneficiaryCoreData: description: The core data of a beneficiary. properties: address_line_1: description: The first address line of the beneficiary. type: string beneficiary_reference: description: The reference for the beneficiary. type: string country_code: description: The ISO 3166-1 alpha-2 code of the beneficiary's country. pattern: '[A-Z]{2}' type: string email_addresses: description: The list of beneficiary's email addresses. items: format: email type: string type: array email_notification: description: >- Whether the beneficiary should receive email notification of payments. type: boolean name: description: The name of the beneficiary. type: string post_code: description: The post code of the beneficiary. type: string type: object securitySchemes: api_key: description: An API Key. in: header name: x-api-key type: apiKey ````