> 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-invite-beneficiary-via-email.md).

# Bulk Invite Beneficiary Via Email

This API is used to send invitations to multiple users . The client submits an array of invitation objects, and each invitation is processed asynchronously. Upon submission, the API responds with a `job_id` that can be used to track the progress and status of the batch operation.

<mark style="color:blue;">**`POST`**</mark> /payments/beneficiaries/bulkimport/invite

**Body Parameters Request**

| Parameter                | Type   | Required | Description                                          |
| ------------------------ | ------ | -------- | ---------------------------------------------------- |
| items                    | array  | Yes      | List of user objects to be invited.                  |
| items\[].firstName       | string | Yes      | First name of the beneficiary.                       |
| items\[].middleName      | string | No       | Middle name of the beneficiary.                      |
| items\[].lastName        | string | Yes      | Last name of the beneficiary.                        |
| items\[].email           | string | Yes      | Email address of the user to be invited.             |
| items\[].beneficiaryId   | string | No       | Optional existing beneficiary ID if already created. |
| items\[].payGroupId      | string | No       | Optional payment group ID the user should belong to. |
| items\[].invoiceCurrency | string | No       | currency code (e.g., "USD", "EUR").                  |
| items\[].user\_tags      | object | No       | Optional custom tags for metadata.                   |

**Body Parameters Response**<br>

| Field               | Type         | Description                                           | Example                                |
| ------------------- | ------------ | ----------------------------------------------------- | -------------------------------------- |
| job\_id             | string       | Unique ID assigned to the batch invitation job        | demo-job-001                           |
| status              | string       | Current status of the job (QUEUED, PROCESSING, DONE)  | DONE                                   |
| total               | integer      | Total number of invitations in the batch              | 2                                      |
| processed           | integer      | Number of invitations successfully processed          | 2                                      |
| failed              | integer      | Number of invitations that failed during processing   | 0                                      |
| processing          | integer      | Number of invitations currently being processed       | 0                                      |
| started\_at         | string (ISO) | Timestamp when job processing started                 | 2025-07-02T21:51:09.437368808Z         |
| completed\_at       | string (ISO) | Timestamp when job processing completed               | 2025-07-02T21:51:09.437375388Z         |
| progress            | array        | Per-row status of each invitation in the batch        | \[{"\_\_row": 0, "status": "SUCCESS"}] |
| progress\[].\_\_row | integer      | Index of the invitation in the submitted array        | 0                                      |
| progress\[].status  | string       | Status of the individual invitation (SUCCESS, FAILED) | SUCCESS                                |

\
\
**Request Example**

<pre class="language-json"><code class="lang-json"><strong>POST /beneficiaries/bulkimport/invite
</strong>{
  "items": [
    {
      "firstName": "John",
      "middleName": "",
      "lastName": "Doe",
      "email": "johndoe1234@gmail.com",
      "inviteMessage": "Custom text messages for invites are currently not supported, but this feature will be available in a future update. Stay tuned!",
      "beneficiaryId": "ab799704-26ed-4076-87fb-e1a88955a4d22",
      "payGroupId": "c5747ec7-a310-4be4-8648-a0ac26d3c5b5",
      "invoiceCurrency": "EUR",
      "user_tags": {}
    },
    {
      "firstName": "Sahil",
      "middleName": "",
      "lastName": "Sid",
      "email": "sahilsid@gmail.com",
      "inviteMessage": "Custom text messages for invites are currently not supported, but this feature will be available in a future update. Stay tuned!",
      "beneficiaryId": "ab799704-26ed-4076-87fb-e1a8895d22",
      "payGroupId": "c5747ec7-a310-4be4-8648-a0ac2c5b5",
      "invoiceCurrency": "EUR",
      "user_tags": {}
    }
  ]
}

</code></pre>

**Response Examples**

{% tabs %}
{% tab title="200  - Success" %}

```json
{
    "job_id": "yVFxTrznRnuSPYQKojbNQg",
    "processing": 0,
    "total": 2,
    "status": "queued",
    "failed": 0,
    "processed": 0,
    "started_at": "2025-07-02T21:50:59.365491818Z",
    "progress": {}
}
```

{% endtab %}

{% tab title="400 - Bad Request" %}

```json
{
    "error": "bad_request",
    "description": "Validation errors: {\"firstName\":\"John\",\"middleName\":\"\",\"email\":\"johndoe12113... at #/items/0 failed against #/properties/items/items with \"Missing property lastName\"",
    "error_code": 400
}
```

{% endtab %}
{% endtabs %}