Planner

List the services to cover

Returns the staff and fleet services of a date window, with who covers them and which resources are needed.

GET

/api/v1/planner/services

curl 'https://app.filmo.io/api/v1/planner/services?startDate=2026-09-01T08%3A00%3A00Z&endDate=2026-09-01T08%3A00%3A00Z' \
  --header "Authorization: Bearer $FILMO_API_KEY"

Node.jsfetch('https://app.filmo.io/api/v1/planner/services?startDate=2026-09-01T08%3A00%3A00Z&endDate=2026-09-01T08%3A00%3A00Z', { headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY' } })Pythonimport requests requests.get( "https://app.filmo.io/api/v1/planner/services?startDate=2026-09-01T08%3A00%3A00Z&endDate=2026-09-01T08%3A00%3A00Z", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY" } )

{
  "data": [
    {
      "orderServiceId": "order_service_9f3a2b",
      "rowKind": "summary",
      "orderId": "order_9f3a2b",
      "orderNumber": "2026-0001",
      "orderStatus": "Example order status",
      "contactName": "Example contact name",
      "projectId": "project_9f3a2b",
      "projectName": "Example project name",
      "serviceId": "service_9f3a2b",
      "serviceName": "Example service name",
      "serviceType": "Example service type",
      "staffMemberId": "staff_member_9f3a2b",
      "vehicleId": "vehicle_9f3a2b",
      "startDate": "2026-09-01T08:00:00.000Z",
      "endDate": "2026-09-01T08:00:00.000Z",
      "status": "Example status",
      "qty": 1,
      "taskId": "task_9f3a2b",
      "requirements": [
        {
          "requiredResourceType": "personnel",
          "qty": 1
        }
      ]
    }
  ]
}

{
  "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": "planner:read"
}

{
  "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

It returns ROWS, not services: each service comes as one summary row (rowKind: summary, with staffMemberId and vehicleId always null) and one detail row per person or vehicle assigned to it, all sharing the same orderServiceId. Group by orderServiceId: a service is uncovered when it only has its summary row, and covered when it has detail rows with an assignee, so a null on the summary row does not mean "uncovered". Internal services (not tied to an order) come with orderId and orderNumber empty and a serviceId that starts with is_. The identifier used to assign is orderServiceId.

Authorizations

Bearer API key with the scope below. planner:read

Query parameters

startDatestring<date-time>Required

Window start, in ISO 8601 with offset.

endDatestring<date-time>Required

Window end, in ISO 8601 with offset.

serviceTypestring

Which services to fetch. Defaults to both.

Available options: crew, fleet, both

orderStatusstring

Filter by status of the order they are attached to.

Available options: draft, reserved, all

projectIdstring

Limit to one project.

Limits: min length 1, max length 100

Response

application/json

Successful response.

Response schema: PlannerServiceDto

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

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

dataobject[]

Show child attributes

data.orderServiceIdstring

Service line identifier. It is the one passed when assigning.

data.rowKindstring

Which row this is. A service comes as ONE summary row (the service itself, with staffMemberId and vehicleId always null) plus one detail row per person or vehicle assigned to it, all with the same orderServiceId. A service is covered when it has detail rows with an assignee, and uncovered when it only has the summary row.

Available options: summary, detail

data.orderIdstring

Order the service is attached to; an empty string on internal services, which belong to no order.

data.orderNumberstring

Human-readable number of that order; an empty string on internal services.

data.orderStatusstring

Order status.

data.contactNamestring | null

Customer of the order; null if not recorded.

data.projectIdstring | null

Associated project; null if not applicable.

data.projectNamestring | null

Project name; null if not applicable.

data.serviceIdstring

Catalogue service it comes from.

data.serviceNamestring

Service name.

data.serviceTypestring

Type: crew, fleet or general.

data.staffMemberIdstring | null

Assigned staff member. Only detail rows carry it; it is null on the summary row even when the service is covered.

data.vehicleIdstring | null

Assigned vehicle. Only detail rows carry it; it is null on the summary row even when the service is covered.

data.startDatestring<date-time>

Service start in ISO 8601 UTC.

data.endDatestring<date-time>

Service end in ISO 8601 UTC.

data.statusstring

Service line status.

data.qtynumber

How many units of the service are requested.

data.taskIdstring | null

Linked schedule task; null if there is none.

data.requirementsobject[]

Resources needed to cover it.

Show child attributes

data.requirements.requiredResourceTypestring

What is needed: personnel or vehicle.

Available options: personnel, vehicle

data.requirements.qtynumber

How many are needed.

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.

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

Operations
Planner service
Staff or fleet service pending coverage, or already covered.

Was this page helpful?

Request examples

Authorizations

Query parameters

Response

Errors

Deprecation

Related

Related pages

Planner service