Staff

Check staff availability

Returns, for each staff member (the whole team, or the ones selected by staffIds, tags, collectionId or search), whether they have commitments overlapping the queried window and which ones, typed: order lines, internal services, declared absences and blocking incidents.

POST

/api/v1/staff/availability

curl https://app.filmo.io/api/v1/staff/availability \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "startDate": "2026-09-01T08:00:00Z",
  "endDate": "2026-09-03T20:00:00Z",
  "staffIds": [
    "stf_ana",
    "stf_luis"
  ]
}'

Node.jsfetch('https://app.filmo.io/api/v1/staff/availability', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ startDate: '2026-09-01T08:00:00Z', endDate: '2026-09-03T20:00:00Z', staffIds: ['stf_ana', 'stf_luis'] }) })Pythonimport requests requests.post( "https://app.filmo.io/api/v1/staff/availability", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Content-Type": "application/json" }, json={ "startDate": "2026-09-01T08:00:00Z", "endDate": "2026-09-03T20:00:00Z", "staffIds": [ "stf_ana", "stf_luis" ] } )

{
  "data": [
    {
      "resourceId": "resource_9f3a2b",
      "name": "Example resource availability entry",
      "available": true,
      "commitments": [
        {
          "kind": "order",
          "orderId": "order_9f3a2b",
          "orderNumber": "2026-0001",
          "label": "Main",
          "startDate": "2026-09-01T08:00:00.000Z",
          "endDate": "2026-09-01T08:00:00.000Z"
        }
      ]
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "staff:read"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

Unlike /api/v1/availability/check, the response is NOT stock arithmetic: a person has no pool, they are either free or on a specific job. A requested identifier that does not exist comes back as a per-item error. Idempotent query (POST because of the structured body). Shares the availability quota of 30 req/min.

Authorizations

Bearer API key with the scope below. staff:read

Body

application/json

Body schema: StaffAvailabilityBody

startDatestring<date-time>Required

Start of the window to check (ISO 8601 with offset).

endDatestring<date-time>Required

End of the window to check (ISO 8601 with offset); must be later than startDate.

tagsstring[]

Only resources carrying ALL these tag identifiers.

Limits: min 1 items, max 50 items, each min length 1, each max length 100

collectionIdstring

Only resources in this collection.

Limits: min length 1, max length 100

searchstring

Free-text search on the name.

Limits: min length 1, max length 200

staffIdsstring[]

Restrict the answer to these staff members (1-100). An identifier that does not exist comes back as a per-item error.

Limits: min 1 items, max 100 items, each min length 1, each max length 100

Response

application/json

Successful response.

Response schema: ResourceAvailabilityEntryDto

Envelope: ResourceAvailabilityEntryItems. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset

dataobject[]

One of 1/2: ResourceAvailability

data.resourceIdstring

Identifier of the queried resource.

data.namestring

Name of the resource.

data.availableboolean

true if there are no commitments, absences or blocking incidents in the window.

data.commitmentsobject[]

Everything that occupies the resource within the window, typed. Empty when the resource is free.

Show child attributes

data.commitments.kindstring

order (a line of an order), internal_service (an internal service, not tied to an order), unavailability (a declared absence) or incident (a blocking incident).

Available options: order, internal_service, unavailability, incident

data.commitments.orderIdstring | null

Order that occupies the resource; null unless kind is order.

data.commitments.orderNumberstring | null

Number of that order; null unless kind is order.

data.commitments.labelstring

What occupies the resource: the service name for orders; a generic label for internal services, absences and incidents (their title or private reason is never exposed).

data.commitments.startDatestring<date-time>

Start of the commitment in ISO 8601 UTC.

data.commitments.endDatestring<date-time>

End of the commitment in ISO 8601 UTC.

One of 2/2: ResourceAvailabilityErrorEntry

data.resourceIdstring

Identifier the request asked for.

data.errorobject

Show child attributes

data.error.codestring

The resource does not exist in the account.

Available options: not_found

data.error.messagestring

Human-readable explanation.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

Status	Codes	Meaning
400	`validation_error`	Malformed query or body. `errors[]` lists every offending field with its stable code.
404	`not_found`	It does not exist or is outside the scope of the API key.
409	`conflict`	The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

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

Was this page helpful?

Request examples

Authorizations

Body

Response

Errors

Deprecation

Related