User
Users belong to a tenant and carry roles that define what they can do. Public v2 endpoints use snake_case keys and are documented in the OpenAPI spec; highlights below.
Endpointsโ
GET /api/v2/usersโ paginated list of tenant users (excluding service accounts).POST /api/v2/usersโ create a user, or invite one by email where people manage their own profile (see Invitations). Email is set on creation and cannot be changed.PATCH /api/v2/users/{user_id}โ JSON Merge Patch (RFC 7396). Omit fields to keep them unchanged; set a field tonullto clear it.lock_versionis optional: when provided it is validated against the stored version (409on mismatch); when omitted the concurrency check is skipped.
Payloadsโ
Create (POST /api/v2/users)โ
{
"email": "bea@example.com",
"firstname": "Bea",
"lastname": "Smith",
"role_ids": ["4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab"],
"phone_number": "+43123456789"
}
Response (created):
{
"id": "1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af",
"email": "bea@example.com",
"roles": ["dispatcher"],
"firstname": "Bea",
"lastname": "Smith",
"profile_status": "COMPLETE",
"created_at": "2024-01-15T10:30:00Z",
"status": "ACTIVE",
"is_profile_self_managed": false
}
Patch (PATCH /api/v2/users/{user_id})โ
Content-Type: application/merge-patch+json (application/json is accepted as an alias)
{
"lock_version": 3,
"firstname": "Bea Updated",
"phone_number": null
}
Notes:
- Email cannot be changed after creation.
role_idsmust never be empty.firstnameandlastnamecannot be cleared. Whereis_profile_self_managedistrue, only the user can change their name and phone number (422 users/profile-self-managedotherwise).
Invitationsโ
In workspaces where people keep one sign-in account for all their Tourfold workspaces, each person
manages their own name and phone number; their users carry is_profile_self_managed: true. There,
POST /api/v2/users invites a person by email:
{
"email": "lena.huber@example.com",
"role_ids": ["4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab"]
}
- A person new to Tourfold gets an invitation email and sets a password; a person who already has a
Tourfold account gets an email that they were added. Either way the user has
profile_status: PENDINGand nofirstname,lastnameorphone_number(the properties are absent) until the person signs in to this workspace for the first time; show the email instead. That sign-in fills the profile and sends auser.updatedwebhook withprofile_status: COMPLETE. - The request carries no
firstname,lastnameorphone_number: only the person sets them. A request with any of them gets422 users/profile-self-managedwithdata.fieldsnaming them, and no user is created. The response does not tell whether the email already had an account. POST /api/v2/users/{user_id}/resend-set-password-emailsends the email again whilecan_resend_set_password_emailistrue.
Where the workspace manages its people's profiles (is_profile_self_managed: false), firstname and
lastname are required and phone_number is optional, as before. A blank name gets a
field-required entry ("must not be blank") next to any other field errors, in every workspace. Once
the other fields are valid, a missing or null name gets 422 validation-failed with a
field-required entry for each missing name.
Rolesโ
List roles for the current tenant with their enabled grants:
GET /api/v2/roles
{
"items": [
{
"id": "4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab",
"name": "dispatcher",
"role_type": "DISPATCHER",
"grants": ["getUsers", "updateUser"]
},
{
"id": "9f3b8e71-766f-4d5d-b9b4-8d57b92a9d52",
"name": "driver",
"role_type": "DRIVER",
"grants": ["getUsers"]
}
]
}