Projects

List project users

List project users using Ovok’s Slim API.

MethodPath
GET/v1/slim/project/:id/users

Authentication · Access policies

Lists the practitioner memberships of a given project: your own project or one of its direct child projects. Use it to manage the team of a child project from its parent.

Auth: Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant Practitioner:read (project admins skip this check). The session must carry a project. Scope: The project in the path. It must be the caller's project (from the token) or a direct child of it. Grandchildren are not reachable.

Request

Path parameters

NameTypeRequiredDescription
idstringYesProject id. Your own project or a direct child of it.

Query parameters

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 20, minimum 1, maximum 100.
profileType"Practitioner"NoKind of member to list. Default Practitioner.
sortBy"profileName" | "userName" | "accessPolicyName"NoSort column. Default profileName.
orderBy"ASC" | "DESC"NoSort direction. Upper case only. Default ASC.
searchstringNoFuzzy match on profile name, user name and access policy name. Trimmed, at least 1 character.
accessPolicyIdstringNoKeep members with this access policy.
profileIdstringNoKeep the member with this practitioner id.
userIdstringNoKeep the member with this user id.

Behaviour

  • The project is read first, so an unknown or out-of-scope id fails before any membership is searched.
  • Rows, filters, sorting, paging and status work exactly as in GET /v1/slim/project/users: one row per Practitioner membership with a user and a profile, search is fuzzy over profile, user and access policy names, count is 1 to 100 (default 20).
  • Answers are cached for up to about a minute.

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/project/b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68/users?count=50' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — Project users retrieved successfully.

{
  "total": 1,
  "page": 0,
  "count": 20,
  "resources": [
    {
      "user": {
        "resourceType": "User",
        "id": "f1b3d5e7-9a2c-4846-b0d8-2c4e6a8f0b13",
        "firstName": "Anna",
        "lastName": "Beispiel",
        "email": "team@example.com",
        "meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "lastUpdated": "2026-10-01T08:00:00.000Z" }
      },
      "profile": {
        "resourceType": "Practitioner",
        "id": "7c9e1a3b-5d4f-4b82-a6c0-8e2f4a6b8d35",
        "name": [{ "given": ["Anna"], "family": "Beispiel" }],
        "telecom": [{ "system": "email", "value": "team@example.com" }],
        "meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "lastUpdated": "2026-10-01T08:00:00.000Z" }
      },
      "membership": {
        "resourceType": "ProjectMembership",
        "id": "e4a6c8f0-2b1d-4973-8a5e-7d9f1b3c5e24",
        "project": { "reference": "Project/b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "display": "Example project" },
        "user": { "reference": "User/f1b3d5e7-9a2c-4846-b0d8-2c4e6a8f0b13", "display": "Anna Beispiel" },
        "profile": { "reference": "Practitioner/7c9e1a3b-5d4f-4b82-a6c0-8e2f4a6b8d35", "display": "Anna Beispiel" },
        "accessPolicy": { "reference": "AccessPolicy/d2c8f4a0-6b3e-4175-9e2d-8a1c5f7b3e46", "display": "Practitioner" },
        "meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "lastUpdated": "2026-10-01T08:00:00.000Z" }
      },
      "status": "Active",
      "accessPolicy": {
        "resourceType": "AccessPolicy",
        "id": "d2c8f4a0-6b3e-4175-9e2d-8a1c5f7b3e46",
        "name": "Practitioner",
        "resource": [{ "resourceType": "Patient", "interaction": ["read", "search"] }],
        "meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "lastUpdated": "2026-09-20T08:00:00.000Z" }
      }
    }
  ]
}
FieldTypeDescription
totalintegerNumber of rows after search, across all pages.
pageintegerPage number of this response.
countintegerPage size of this response.
resourcesobject[]The rows of this page. One per practitioner membership.
resources[].userobjectThe member's user account.
resources[].user.resourceType"User"Always User.
resources[].user.idstring (uuid)User id.
resources[].user.firstNamestringFirst name. Left out when not set.
resources[].user.lastNamestringLast name. Left out when not set.
resources[].user.emailstringEmail address. Left out when not set.
resources[].user.projectobjectReference to the project the user account is scoped to, with reference and display. Left out for an account that is not scoped to one project.
resources[].user.metaobjectResource metadata: project and lastUpdated.
resources[].profileobjectThe member's Practitioner profile, with every element it has, such as name and telecom. Only project and lastUpdated of its meta are kept.
resources[].membershipobjectThe ProjectMembership of the member.
resources[].membership.resourceType"ProjectMembership"Always ProjectMembership.
resources[].membership.idstring (uuid)Membership id.
resources[].membership.projectobjectReference to the project, with reference and display.
resources[].membership.userobjectReference to the user, with reference and display.
resources[].membership.profileobjectReference to the practitioner, with reference and display.
resources[].membership.accessPolicyobjectReference to the access policy, with reference and display. Left out when the membership has none.
resources[].membership.metaobjectResource metadata: project and lastUpdated.
resources[].status"Active" | "Pending"Pending while the user has an unused invite or has never set a password.
resources[].accessPolicyobjectThe member's access policy. Left out when the membership has none.
resources[].accessPolicy.resourceType"AccessPolicy"Always AccessPolicy.
resources[].accessPolicy.idstring (uuid)Access policy id.
resources[].accessPolicy.namestringPolicy name. Left out when not set.
resources[].accessPolicy.resourceobject[]The policy's rules, one per resource type, as stored.
resources[].accessPolicy.metaobjectResource metadata: project and lastUpdated.

Errors

StatusMeaning
400The project is neither the caller's project nor a direct child of it, or it cannot be read.
401The bearer token is missing or invalid.
403The session is not a practitioner, admin or System Owner session, has no project, or its access policy lacks Practitioner:read.
422A path or query parameter fails validation.

Last updated on

On this page