Users and roles

A Resi user is one login. A user can belong to several accounts and has a role in each one. The role decides what they can do there, including what API tokens they create can do. The users endpoints manage the members of the current account.

RolesCopy Anchor Link

Every account has four built-in roles: admin, manager, member and viewer. It can also define custom roles in the Resi app. Wherever V2 takes a role, it accepts:

• a built-in role key, such as manager;
• the slug of a custom role;
• the id of any of the account's roles.

Every user in a response carries role (the key or slug), role_id (stable across renames) and role_name (the display name). Store role_id if you need to recognise a role later.

GET /api/v2/roles lists the account's roles, with the key a user's role takes and what each role may do (permissions, by resource). It needs permission to view users. Roles are created and edited in the Resi app.

Invite a userCopy Anchor Link

POST /api/v2/users takes a name, an email and an optional role:

curl -X POST https://v2.getresi.com/api/v2/users \
  -H "Authorization: Bearer $RESI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jordan Lee", "email": "jordan@example.com", "role": "manager" }'

The user gets an email inviting them to set a password. No password is ever sent or accepted through the API.

• Without role, the user gets the account's default role. Only admins can assign any other role.
• The email must be new to Resi. If the person already has a Resi login, for another account, the request is a 422; add them to this account in the Resi app instead.

Change a role, name or emailCopy Anchor Link

PATCH /api/v2/users/{user} changes any of role, name and email.

• Only admins can change roles. No one can change their own role, and the account always keeps at least one admin.
• name and email belong to the person, not the account: they are the same in every account the user belongs to, and the email is their login. So they can only be changed for a user who belongs to no other account and is not Resi staff, or by the user themselves. Anything else is a 403.

Remove a userCopy Anchor Link

DELETE /api/v2/users/{user} removes the user from the current account. Their login, and their membership of any other account, are untouched. You cannot remove yourself, and only admins can remove an admin.

API tokens the user created for this account stop working when they leave it.