> For the complete documentation index, see [llms.txt](https://docs.papayaglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.papayaglobal.com/api-reference/beneficiaries-management/bulk-import-beneficiary.md). # Bulk Import Beneficiary The API generates a group of multiple beneficiaries by making a single request within the account. After registration, the beneficiary ID can be used to transmit payment instructions, and the job ID can be used on the status endpoint to check the job status. **`POST`** /payments/beneficiaries/import **Body Parameters Request** | Name | Type | Format / Values | Description | Required | | ---------------------- | ------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | -------- | | update\_payments | boolean | | When set to true, will update the beneficiary details for all pending payments created for the same beneficiary | | | signature | string | | | | | items | array | object | | | | items\[] | object | | | | | items\[].id | string | | | | | items\[].country | string | /^\[A-Z]{2,2}$/ | | | | items\[].currency | string | /^\[A-Z]{3,3}$/ | | | | items\[].entity\_type | string | INDIVIDUAL, BUSINESS | | | | items\[].bank\_details | object | | | | | items\[].entity | object | | | | **Body Parameters Response** | Name | Type | Format / Values | Description | | ------------------------------------------------------- | ------- | --------------- | ----------------------------------------------------- | | job\_id | string | | The job id assigned to this import | | started\_at | string | date-time | The time the import job started | | processed | integer | | The total number of items processed so far | | total | integer | | Total number of items in bulk | | processing | integer | | The number of items currently being processed | | failed | integer | | Total number of failed items | | status | string | QUEUED, DONE | The current job status | | progress | array | object | List of item progress | | progress\[] | object | | | | progress\[].row | integer | | The index of the item | | progress\[].error | object | | Information regarding error encountered for this item | | progress\[].error.error\_info | object | | | | progress\[].error.error\_info.valid | boolean | | Is this item valid | | progress\[].error.error\_info.warnings | array | object | List of warnings encountered for this item | | progress\[].error.error\_info.warnings\[] | object | | | | progress\[].error.error\_info.warnings\[].description | string | | Description of issue | | progress\[].error.error\_info.warnings\[].properties | array | string | the properties this issue applies to | | progress\[].error.error\_info.warnings\[].properties\[] | string | | | | progress\[].error.error\_info.errors | array | object | List of errors encountered for this item | | progress\[].error.error\_info.errors\[] | object | | | | progress\[].error.error\_info.errors\[].description | string | | Description of issue | | progress\[].error.error\_info.errors\[].properties | array | string | the properties this issue applies to | | progress\[].error.error\_info.errors\[].properties\[] | string | | | | progress\[].error.error\_code | integer | | The error code associated with this issue | | progress\[].error.error | string | | error type encountered | | progress\[].error.message | string | | Human readable error information | | progress\[].status | string | FAILED, SUCCESS | The status of this item's impo | **Request Example** ```json POST /payments/beneficiaries/import { "items": [ { "id": "1", "entity_type": "INDIVIDUAL", "bank_details": { "account_number": "789456123012", "bank_code": "111000025", "account_country": "US", "account_currency": "USD", "account_name": "Anderson Emily" }, "entity": { "individual_last_name": "Anderson", "address_country_subdivision": "TX", "individual_first_name": " Emily", "date_of_birth": "1985-06-05", "address_line_1": "1234 Elm Street", "address_city": "Houston", "address_country": "US", "address_postal_code": "77001" } }, { "id": "2", "entity_type": "INDIVIDUAL", "bank_details": { "bank_name": "BANK OF AMERICA", "account_number": "234567890567", "bank_code": "111000025", "account_country": "US", "account_currency": "USD", "account_name": "Patel Jason" }, "entity": { "individual_last_name": "Patel", "address_country_subdivision": "TX", "individual_first_name": " Jason", "date_of_birth": "1986-12-02", "address_line_1": "1235 Elm Street", "address_city": "Houston", "address_country": "US", "address_postal_code": "77001" } }, { "id": "3", "entity_type": "INDIVIDUAL", "bank_details": { "bank_name": "Bank of America", "account_number": "654321098765", "bank_code": "111000025", "account_country": "US", "account_currency": "USD", "account_name": "Garcia Olivia" }, "entity": { "individual_last_name": "Garcia", "address_country_subdivision": "TX", "individual_first_name": " Olivia", "date_of_birth": "1972-11-25", "address_line_1": "1236 Elm Street", "address_city": "Houston", "address_country": "US", "address_postal_code": "77001" } } ] } ``` **Response Examples** {% tabs %} {% tab title="202 - Accepted" %} ```json { "job_id": "TPy4DcQATiqZRRzTMEXt2Q", "started_at": "2024-03-04T10:56:51.126587470Z", "processed": 0, "total": 3, "processing": 2, "failed": 1, "status": "QUEUED" "progress": [ { "row": 0, "error": { "error_info": { "valid": false, "warnings": [], "errors": [ { "description": "Missing property bank_name", "properties": [ "$.bank_details" ] } ] }, "error_code": 422, "error": "unprocessable_entity", "message": "Payload object is invalid." }, "status": "FAILED" } ] } ``` {% endtab %} {% tab title="404 - Bad Request" %} ```json { "error": "bad_request", "description": "Validation errors: \"US\" at #/items/0/currency failed against #/properties/items/items/properties/currency with \"Did not match pattern: ^[A-Z]{3,3}$\"", "error_code": 400 } ``` {% endtab %} {% endtabs %}