> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/cookbooks/platform-admin/give-people-access/invite-someone.md).

# Invite a user

Create a user record, assign roles, and send the invitation.

`POST /users` creates a user record in your account and sends the invitation. This is the API equivalent of [Invite a user](https://docs.uptiq.ai/platform-guides/admin/give-people-access/invite-a-user).

## At a glance

| Item            | Value                                           |
| --------------- | ----------------------------------------------- |
| ⚙️ Microservice | `Identity Hub`                                  |
| 🌍 Environment  | `QA`                                            |
| 🔗 Base URL     | `https://api-builder-qa.uptiq.dev/identity-hub` |
| ⌘ Endpoint      | `POST /users`                                   |

{% columns %}
{% column %}

#### What it does

Creates an account user, assigns any supplied roles, and sends an invitation.
{% endcolumn %}

{% column %}

#### Success looks like

The service returns `201 Created` and the new user's ID.
{% endcolumn %}
{% endcolumns %}

{% hint style="warning" %}
**Don't confuse this with `POST /admin/users`.** That path is for platform operators. It requires `accountId` in the body. Your account API key can call `POST /users`.
{% endhint %}

## Before you start

| You need                      | Why                                                                                                                                       |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| 🔑 **Create user** capability | Authorizes the request (`CreateUser`). See [Capabilities by role](https://docs.uptiq.ai/control-center/admin/roles#capabilities-by-role). |
| 🆔 `roleIds`                  | Determines the person's access. Saving sends the invitation immediately.                                                                  |

## Request

`POST /users`

| Field               | Type    | Required | What it does                                                                                                 |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `email`             | string  | Yes      | Where the invitation goes, and how the person signs in.                                                      |
| `firstName`         | string  | Yes      |                                                                                                              |
| `lastName`          | string  | Yes      |                                                                                                              |
| `phoneNumber`       | string  | No       | Include the country code.                                                                                    |
| `roleIds`           | array   | No       | Role IDs to assign. Omit to create with no role — the person can sign in but do nothing until you grant one. |
| `sendEmail`         | boolean | No       | Whether to send the invitation email. Defaults to sending it.                                                |
| `initialAuthMethod` | string  | No       | `Password`, `GoogleSSO`, or `Pending`.                                                                       |

## Code snippets

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api-builder-qa.uptiq.dev/identity-hub/users \
  -H "x-platform-key: YOUR_API_KEY" \
  -H "accountid: YOUR_ACCOUNT_ID" \
  -H "content-type: application/json" \
  -d '{
    "email": "alex@yourbank.com",
    "firstName": "Alex",
    "lastName": "Rivera",
    "roleIds": ["role_developer"]
  }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const res = await fetch("https://api-builder-qa.uptiq.dev/identity-hub/users", {
  method: "POST",
  headers: {
    "x-platform-key": process.env.UPTIQ_API_KEY,
    accountid: process.env.UPTIQ_ACCOUNT_ID,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    email: "alex@yourbank.com",
    firstName: "Alex",
    lastName: "Rivera",
    roleIds: ["role_developer"],
  }),
});
const { data } = await res.json();
console.log(data.id);
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

res = requests.post(
    "https://api-builder-qa.uptiq.dev/identity-hub/users",
    headers={
        "x-platform-key": os.environ["UPTIQ_API_KEY"],
        "accountid": os.environ["UPTIQ_ACCOUNT_ID"],
    },
    json={
        "email": "alex@yourbank.com",
        "firstName": "Alex",
        "lastName": "Rivera",
        "roleIds": ["role_developer"],
    },
)
user = res.json()["data"]
print(user["id"])
```

{% endtab %}
{% endtabs %}

## Response

| Result          | What it means                                                       | Next action                                                             |
| --------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| ✅ `201 Created` | `data` contains only the new user's `id`, not the full user record. | Call `GET /users/{id}` to retrieve status, roles, and onboarding state. |

{% hint style="success" %}
**Verified against QA on 22 September 2026.** Field names and nesting below are exactly as returned; identifiers and personal data are placeholders.
{% endhint %}

```json
{
  "message": "User created successfully",
  "data": {
    "id": "571781cc-f16d-4652-9042-3ef90e82efc4"
  }
}
```

## Developer notes

| Situation                        | What to do                                                                               |
| -------------------------------- | ---------------------------------------------------------------------------------------- |
| ⚠️ `roleIds` are unavailable     | Call `GET /roles` first. Send role IDs, not role names.                                  |
| ⚠️ `roleIds` are omitted         | The user has no permissions. This supports workflows with a separate role-approval step. |
| ⚠️ The invitation needs changing | Use `POST /users/{id}/resend-invite` or `POST /users/{id}/revoke-invite`.                |

### Suppress emails

Two optional body fields control what gets sent, and both matter when scripting against a real account:

| Field                        | Effect                                       |
| ---------------------------- | -------------------------------------------- |
| `sendEmail`                  | `false` suppresses the new-user email        |
| `skipAccountInvitationEmail` | `true` skips the "added to an account" email |

Set both when seeding test users, or every run mails a real person.

{% hint style="warning" %}
**A user record cannot be deleted.** There is no `DELETE /users` — only `deactivate`, `revoke-invite` and `activate`. Every invitation you create is permanent, so use addresses you are willing to leave in the account forever.
{% endhint %}

## Related

| Related cookbook                                                                                 | When to use it                             |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Invite a user](https://docs.uptiq.ai/platform-guides/admin/give-people-access/invite-a-user)    | Use the Control Center instead of the API. |
| [Change a user's roles](/cookbooks/platform-admin/give-people-access/change-someones-access.md)  | Adjust roles after the invitation.         |
| [Remove a user's access](/cookbooks/platform-admin/give-people-access/remove-someones-access.md) | Offboard the person.                       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.uptiq.ai/cookbooks/platform-admin/give-people-access/invite-someone.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.