Invite Beneficiary By Email

The API is utilised to send the invitation to a single user by email

POST /beneficiaries/invite

Body Parameters Request

Parameter	Type	Required	Description
firstName	string	Yes	Beneficiary’s first name.
middleName	string	No	Middle name of the beneficiary.
lastName	string	Yes	Beneficiary’s last name.
email	string	Yes	Email address where the invite will be sent.
beneficiaryId	string	No	Will Create new Id if not provided
payGroupId	string	No	ID of the payment group the user should belong to.
invoiceCurrency	string	No	currency code e.g. ("EUR", "USD").
user_tags	object	No	Custom metadata for the user (key-value pairs).

Body Parameter Response

Parameter	Type	Required	Description	Example
invite.user_id	string	Yes	ID of the invited user	b8094933-639a-41dc-89e0-c9e432adf3b5
invite.user_psa_status	string	Yes	Status of the PSA invitation	INVITED
invite.invite_expires_at	string (ISO)	Yes	Expiration datetime of the invite	2025-07-09T21:42:14
update	boolean	Yes	Indicates if this is an update operation	true
create	boolean	Yes	Indicates if this is a create operation	true
name.firstName	string	Yes	Beneficiary’s first name	John
name.middleName	string	No	Middle name of the beneficiary	(empty)
name.lastName	string	Yes	Beneficiary’s last name	Doe
name.email	string	Yes	Email address where the invite is sent	[email protected]
name.beneficiaryId	string	No	Existing beneficiary ID	ab799704-26ed-4076-87fb-e1a88955a4d22
name.payGroupId	string	No	ID of the payment group	98ec9c37-b60f-4722-ad13-8c974d95eadc
name.invoiceCurrency	string	No	Currency code (e.g., "EUR", "USD")	EUR
name.user_tags	object	No	Custom metadata for the user (key-value pairs)	{}
name.org_id	string	Yes	Organization ID	54309000
name.user_id	string	Yes	Internal user ID	2debe167-8dd4-438a-9051-88597061af44
name.roles	array	Yes	Roles assigned to the user	["SA_INVOICE_SUBMISSION_ADMIN"]

Request Example

POST /beneficiaries/invite
{
  "firstName": "John",
  "middleName": "",
  "lastName": "Doe",
  "email": "[email protected]",
  "beneficiaryId": "ab799704-26ed-4076-87fb-e1a88955a4d22", //optional 
  "payGroupId": "c5747ec7-a310-4be4-8648-a0ac26d3c5b5",//optional
  "invoiceCurrency": "EUR", //optional
  "user_tags": {} //optional
}

Response Example

200 - Sent

{
  "invite": {
    "user_id": "demo-user-1234",
    "user_psa_status": "INVITED",
    "invite_expires_at": "2025-07-09T21:42:14"
  },
  "update": true,
  "create": true,
  "name": {
    "firstName": "Alice",
    "middleName": "",
    "lastName": "Smith",
    "email": "[email protected]",
    "beneficiaryId": "demo-beneficiary-5678",
    "payGroupId": "demo-paygroup-001",
    "invoiceCurrency": "USD",
    "user_tags": {
      "department": "Finance",
      "region": "North America"
    },
    "org_id": "demo-org-1001",
    "user_id": "internal-user-9999",
    "payGroup": {
      "type": "group",
      "id": "demo-paygroup-001",
      "description": "Demo Pay Group for Testing",
      "name": "Demo USD Group",
      "locked": false,
      "user_tags": {},
      "wallet": {
        "type": "wallet",
        "id": "wallet-abc-123",
        "currency": "USD",
        "name": "Demo Wallet",
        "balance": 50000.00,
        "owner": "entity://business/customer/demo-org-1001/legal/demo-entity-789"
      },
      "info": {
        "funding": {
          "next": "2025-12-01",
          "missing_funds": 20000.00
        },
        "payments": {
          "total": 100,
          "pending": 20,
          "pending_approval": 10,
          "issues": 5,
          "completed": 75,
          "failed": 0,
          "routing": 2,
          "next": "2025-12-01",
          "amount": {
            "amount": 45000.00,
            "currency": "USD"
          }
        }
      }
    },
    "roles": [
      "SA_INVOICE_SUBMISSION_ADMIN"
    ],
    "owner": {
      "ownerId": "demo-org-1001",
      "ownerType": "org_id"
    }
  }
}

409 - BENEFICIARY_EXISTS

{
    "error": "BENEFICIARY_EXISTS",
    "description": "Beneficiary id already exists",
    "error_code": 409
}

409 - Email Already Exists

{
    "error": "unknown_exception",
    "error_code": 400,
    "error_info": {
        "description": "Email already in use by other beneficiary",
        "error_code": 409,
        "error": "EMAIL_ALREADY_IN_USE"
    }
}

400 - Bad Request

{
    "error": "bad_request",
    "description": "Validation errors: {\"middleName\":\"\",\"lastName\":\"Doe\",\"email\":\"johndoe129qqq9... at root failed with \"Missing property firstName\"",
    "error_code": 400
}