Invite a user
POST/v1/directory/people
Adds someone to your organization and emails them an invitation to set up their sign-in. They are invited until they accept.
Permission: identity:CreateUser. Changes need a sign-in that used a second factor.
Body
| Field | Type | Description |
|---|---|---|
email |
string | Required. Their email address. |
username |
string | Required. Lowercase letters only; it can't be changed later. |
given_name |
string | Their first name. |
family_name |
string | Their last name. |
Returns
201 Created
{
"person": {
"id": "8f0c2c1e-6b1a-4f3e-9a51-0c3d2f7e9b10",
"email": "pat@example.com",
"username": "patlee",
"name": "Pat Lee",
"given_name": "Pat",
"family_name": "Lee",
"status": "invited",
"email_verified": false,
"last_sign_in_at": null,
"mfa_devices": 0,
"profile_managed": false,
"created_at": "2026-11-19T09:00:00Z",
"updated_at": "2026-11-19T09:00:00Z"
},
"invitation_sent": true
}invitation_sent is false when the email couldn't go; the person is invited either way, and Resend invitation sends it again.
Errors
Besides the errors every call can return:
| Status | When |
|---|---|
400 |
A missing or malformed email, username or name. |
409 |
Someone in your organization has that username, or that address already has an account. |
Example
curl -X POST https://<company>.yotta.bot/v1/directory/people \
-H "Authorization: Bearer $YOTTABOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": "pat@example.com", "username": "patlee", "given_name": "Pat", "family_name": "Lee"}'With yottactl
yottactl org users invite \
--set email=pat@example.com \
--set username=patlee \
--set given_name=Pat \
--set family_name=Lee