> ## 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. # Create a mass beneficiary instruction > Submit a new mass beneficiary instruction to create beneficiaries in bulk. The instruction is processed asynchronously. ## OpenAPI ````yaml /openapi/ebury-api-public.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: [] paths: /mass-beneficiaries: post: tags: - Mass Beneficiaries summary: Create a mass beneficiary instruction description: >- Submit a new mass beneficiary instruction to create beneficiaries in bulk. The instruction is processed asynchronously. parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/Authorization' requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/NewBeneficiary' description: The list of beneficiaries to create. required: true responses: '202': description: Mass beneficiary request accepted, see response body for status content: application/json: schema: $ref: '#/components/schemas/MassBeneficiary' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/ClientNotFound' '415': $ref: '#/components/responses/UnsupportedMediaType' '502': $ref: '#/components/responses/IntegrationError' components: parameters: ClientId: description: The identifier of a client. in: query name: client_id required: true schema: type: string Authorization: description: The access token. in: header name: Authorization required: true schema: type: string schemas: 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 MassBeneficiary: description: This model is a representation of a mass beneficiary. type: object properties: mass_beneficiary_id: description: Unique UUID of the mass beneficiary. type: string format: uuid error: allOf: - $ref: '#/components/schemas/ErrorMessage' description: The generic error message for the mass beneficiary request, if any. nullable: true links: $ref: '#/components/schemas/MassBeneficiaryLinks' summary: $ref: '#/components/schemas/MassBeneficiarySummary' status: $ref: '#/components/schemas/MassBeneficiaryStatus' required: - mass_beneficiary_id - error - links - summary - status 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 apartment_office_number: description: >- The apartment/office number of the beneficiary. Does not apply to Ebury Mass Payments customers. maxLength: 70 type: string beneficiary_reference: description: The reference for the beneficiary. maxLength: 255 pattern: ^[\sa-zA-Z0-9\d,\.:'\+\(\)\?'\-/]*$ type: string building_number: description: >- The building number of the beneficiary. Does not apply to Ebury Mass Payments customers. maxLength: 16 type: string city: description: >- The city of the beneficiary. Does not apply to Ebury Mass Payments customers. maxLength: 35 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 floor: description: >- The floor of the beneficiary. Does not apply to Ebury Mass Payments customers. maxLength: 70 type: string name: description: The name of the beneficiary. type: string post_code: description: The post code of the beneficiary. type: string state_region: description: >- The state/region of the beneficiary. Does not apply to Ebury Mass Payments customers. maxLength: 35 type: string street_name: description: >- The street name of the beneficiary. Does not apply to Ebury Mass Payments customers. maxLength: 70 type: string 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 MassBeneficiaryLinks: description: >- Links to the resources related to the errored and successfully created beneficiaries of a mass beneficiary. The `mass_beneficiary_id` does not need to be stored, as these resources may be accessed with the provided links. type: object properties: errors_href: description: >- The link to the errors endpoint `/mass-beneficiaries/{mass_beneficiary_id}/errors`. type: string created_href: description: >- The link to the created beneficiaries endpoint `/mass-beneficiaries/{mass_beneficiary_id}/beneficiaries`. type: string required: - errors_href - created_href MassBeneficiarySummary: description: Categorized counters for the mass beneficiary. type: object properties: received: description: Total count of received beneficiaries. type: integer created: description: Total count of created beneficiaries. type: integer errored: description: Total count of errored beneficiaries. type: integer required: - received - created - errored MassBeneficiaryStatus: description: |- The status of a mass beneficiary instruction: * `pending`: The mass beneficiary is pending to be processed. * `creating`: The mass beneficiary is being processed. * `created`: The mass beneficiary has been successfully processed. * `failed`: The mass beneficiary has failed during processing. * `unknown`: The mass beneficiary has an unknown status. type: string enum: - pending - creating - created - failed - unknown responses: ValidationError: description: >- Formatting, parameter or schema validation error. See error message for further details. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' Unauthorized: description: Access denied due to authentication failure. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' Forbidden: description: >- Could not complete action due to data constraints. Refer to error message for additional details. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' ClientNotFound: description: Client identifier not found. UnsupportedMediaType: description: >- Entity body in unsupported format. The Content-Type header must be application/json. content: application/json: schema: properties: code: description: The code for the error. enum: - NOT_VALID_CONTENT_TYPE type: string message: type: string description: A short description of the cause of the error. required: - code - message type: object IntegrationError: description: Internal integration error. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' ````