Skip to main content

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 to null to clear it. lock_version is optional: when provided it is validated against the stored version (409 on 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_ids must never be empty.
  • firstname and lastname cannot be cleared. Where is_profile_self_managed is true, only the user can change their name and phone number (422 users/profile-self-managed otherwise).

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: PENDING and no firstname, lastname or phone_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 a user.updated webhook with profile_status: COMPLETE.
  • The request carries no firstname, lastname or phone_number: only the person sets them. A request with any of them gets 422 users/profile-self-managed with data.fields naming 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-email sends the email again while can_resend_set_password_email is true.

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"]
}
]
}