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.
POST /beneficiaries/bulkimport/invite
Body Parameters Request
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
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
POST /beneficiaries/bulkimport/invite
{
"items": [
{
"firstName": "John",
"middleName": "",
"lastName": "Doe",
"email": "[email protected]",
"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": "[email protected]",
"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": {}
}
]
}
Response Examples
{
"job_id": "yVFxTrznRnuSPYQKojbNQg",
"processing": 0,
"total": 2,
"status": "queued",
"failed": 0,
"processed": 0,
"started_at": "2025-07-02T21:50:59.365491818Z",
"progress": {}
}Last updated