# List project users

Canonical page: https://docs.ovok.com/slim-apis/project/list-project-users

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/project/:id/users` |

[Authentication](/authentication) · [Access policies](/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 [#request]

### Path parameters [#path-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | Project id. Your own project or a direct child of it. |

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Zero-based page number. Default `0`, minimum `0`. |
| `count` | `integer` | No | Rows per page. Default `20`, minimum `1`, maximum `100`. |
| `profileType` | `"Practitioner"` | No | Kind of member to list. Default `Practitioner`. |
| `sortBy` | `"profileName"` \| `"userName"` \| `"accessPolicyName"` | No | Sort column. Default `profileName`. |
| `orderBy` | `"ASC"` \| `"DESC"` | No | Sort direction. Upper case only. Default `ASC`. |
| `search` | `string` | No | Fuzzy match on profile name, user name and access policy name. Trimmed, at least 1 character. |
| `accessPolicyId` | `string` | No | Keep members with this access policy. |
| `profileId` | `string` | No | Keep the member with this practitioner id. |
| `userId` | `string` | No | Keep the member with this user id. |

## Behaviour [#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 [#example]

```bash
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 [#successful-response]

`200` — Project users retrieved successfully.

```json
{
  "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" }
      }
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of rows after `search`, across all pages. |
| `page` | `integer` | Page number of this response. |
| `count` | `integer` | Page size of this response. |
| `resources` | `object[]` | The rows of this page. One per practitioner membership. |
| `resources[].user` | `object` | The member's user account. |
| `resources[].user.resourceType` | `"User"` | Always `User`. |
| `resources[].user.id` | `string (uuid)` | User id. |
| `resources[].user.firstName` | `string` | First name. Left out when not set. |
| `resources[].user.lastName` | `string` | Last name. Left out when not set. |
| `resources[].user.email` | `string` | Email address. Left out when not set. |
| `resources[].user.project` | `object` | Reference 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.meta` | `object` | Resource metadata: `project` and `lastUpdated`. |
| `resources[].profile` | `object` | The member's [`Practitioner`](/api/fhir/r4/practitioner) profile, with every element it has, such as `name` and `telecom`. Only `project` and `lastUpdated` of its `meta` are kept. |
| `resources[].membership` | `object` | The `ProjectMembership` of the member. |
| `resources[].membership.resourceType` | `"ProjectMembership"` | Always `ProjectMembership`. |
| `resources[].membership.id` | `string (uuid)` | Membership id. |
| `resources[].membership.project` | `object` | Reference to the project, with `reference` and `display`. |
| `resources[].membership.user` | `object` | Reference to the user, with `reference` and `display`. |
| `resources[].membership.profile` | `object` | Reference to the practitioner, with `reference` and `display`. |
| `resources[].membership.accessPolicy` | `object` | Reference to the access policy, with `reference` and `display`. Left out when the membership has none. |
| `resources[].membership.meta` | `object` | Resource metadata: `project` and `lastUpdated`. |
| `resources[].status` | `"Active"` \| `"Pending"` | `Pending` while the user has an unused invite or has never set a password. |
| `resources[].accessPolicy` | `object` | The member's access policy. Left out when the membership has none. |
| `resources[].accessPolicy.resourceType` | `"AccessPolicy"` | Always `AccessPolicy`. |
| `resources[].accessPolicy.id` | `string (uuid)` | Access policy id. |
| `resources[].accessPolicy.name` | `string` | Policy name. Left out when not set. |
| `resources[].accessPolicy.resource` | `object[]` | The policy's rules, one per resource type, as stored. |
| `resources[].accessPolicy.meta` | `object` | Resource metadata: `project` and `lastUpdated`. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | The project is neither the caller's project nor a direct child of it, or it cannot be read. |
| [`401`](/errors/unauthenticated) | The bearer token is missing or invalid. |
| [`403`](/errors/forbidden) | The session is not a practitioner, admin or System Owner session, has no project, or its access policy lacks `Practitioner:read`. |
| [`422`](/errors/validation-failed) | A path or query parameter fails validation. |
