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