*REST API › Endpoint reference › Operations › Staff*

# List staff

> Returns the staff with the MINIMUM projection needed to plan: who exists, what type they are, whether they drive and whether they appear in the planner.

It does NOT include contact, identity, employment, banking or platform access data, and that is deliberate: to write to someone there is the `contacts` resource, with its own scope. Sorted by name.

`GET /api/v1/staff` — scope `staff:read`

Scope: `staff:read` · 120/min · Strict tenancy · MCP: `filmo_staff_list`

## Authorizations

Bearer API key with the scope below. `staff:read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Page size (1-500). Defaults to 50. = `50` |
| `cursor` | string | No | Opaque cursor of the page to return. Pass the value of `pagination.nextCursor` from the previous response; treat it as opaque. |
| `createdOn` | string | No | The creation date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdAfter` | string | No | The creation date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdBefore` | string | No | The creation date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdFrom` | string | No | The creation date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdTo` | string | No | The creation date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedOn` | string | No | The last update date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedAfter` | string | No | The last update date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedBefore` | string | No | The last update date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedFrom` | string | No | The last update date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedTo` | string | No | The last update date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `q` | string | No | Free-text search on the name. |
| `sort` | string | No | Sort order: up to 3 comma-separated fields, each with a leading "-" for descending (e.g. "-updatedAt,name"). Sortable fields: createdAt, updatedAt, fullName, staffType. Defaults to "fullName". Ties are broken by id, so the order is stable across pages, and a cursor is bound to the sort it was issued with. |
| `staffType` | string | No | Filter by staff member type. `employee`, `freelancer`, `contractor` |
| `staffTypes` | string[] | No | Filter by staffType, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. `employee`, `freelancer`, `contractor` |
| `hasDrivingLicense` | boolean | No | Filter by driving licence, useful for assigning transport. |
| `includeTotal` | boolean | No | Set it to true to include `pagination.total`, the number of results that match the filters across all pages. Off by default. = `false` |

## Request examples

*List staff*

**cURL**

```bash
curl https://app.filmo.io/api/v1/staff \
  --header "Authorization: Bearer $FILMO_API_KEY"
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/staff', {
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY'
  }
})
```

**Python**

```python
import requests

requests.get("https://app.filmo.io/api/v1/staff",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY"
    }
)
```

## Response

Response schema: `StaffMemberDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. |
| 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. |
| 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. |
| 500 | Internal error (internal_error). |

**200**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object[] |  |
| `data.id` | string | Unique staff member identifier. |
| `data.fullName` | string | Full name. |
| `data.staffType` | string | Staff member type. `employee`, `freelancer`, `contractor` |
| `data.collectionId` | string | Identifier of the collection it belongs to; null if it is in none. |
| `data.collectionName` | string | Collection path it belongs to; null if not applicable. |
| `data.hasDrivingLicense` | boolean | true if they hold a driving licence. |
| `data.showInPlanner` | boolean | true if they appear in the planner of the account. |
| `data.externalRef` | string | External reference for matching with third-party systems; null if it has none. |
| `data.createdAt` | string<date-time> | Creation date in ISO 8601 UTC; null if not recorded. |
| `data.updatedAt` | string<date-time> | Last modification date in ISO 8601 UTC; null if not recorded. |
| `pagination` | object | Opaque-cursor pagination metadata. |
| `pagination.nextCursor` | string | Opaque cursor of the next page; null when there are no more results. Pass it as `cursor` in the next request. |
| `pagination.hasMore` | boolean | Whether more results exist beyond this page. |
| `pagination.total` | integer | Number of results matching the filters across all pages. Present only when the request sets `includeTotal=true`. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 200*

```json
{
  "data": [
    {
      "id": "staff_member_9f3a2b",
      "fullName": "Example full name",
      "staffType": "employee",
      "collectionId": "collection_9f3a2b",
      "collectionName": "Example collection name",
      "hasDrivingLicense": true,
      "showInPlanner": true,
      "externalRef": "Example external ref",
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |

## Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date.

---

Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/staff/list-staff  
Last updated: 2026-10-25