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

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

202 - Accepted

{
  "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"
    }
  ] 
}

404 - Bad Request

{
  "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
}