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

# Invite Beneficiary By Email

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

<mark style="color:green;">**`POST`**</mark> /payments/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         | <johndoe1234@gmail.com>               |
| 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**

```json
POST /beneficiaries/invite
{
  "firstName": "John",
  "middleName": "",
  "lastName": "Doe",
  "email": "johndoe1234@gmail.com",
  "beneficiaryId": "ab799704-26ed-4076-87fb-e1a88955a4d22", //optional 
  "payGroupId": "c5747ec7-a310-4be4-8648-a0ac26d3c5b5",//optional
  "invoiceCurrency": "EUR", //optional
  "user_tags": {} //optional
}
```

**Response Example**

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

```json
{
  "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": "alice.smith@example.com",
    "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"
    }
  }
}
```

{% endtab %}

{% tab title="409 - BENEFICIARY\_ALREADY\_EXISTS" %}

```json
{
    "error": "BENEFICIARY_ALREADY_EXISTS",
    "description": "Beneficiary id already exists",
    "error_code": 400
}
```

{% endtab %}

{% tab title="409 - EMAIL\_ALREADY\_IN\_USE" %}

```json
{
    "error": "EMAIL_ALREADY_IN_USE",
    "description": "Email already in use by other beneficiary",
    "error_code": 409
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}