Copy page

Resource Guides

People And Scheduling

People and scheduling endpoints expose user references, absences, shifts, and shift day notes used by editorial planning workflows.

Use this page for v2 behavior. Use the Users API reference, Absences API reference, and Shifts API reference for exact schemas, examples, response codes, and endpoint-specific validation.

Users

Users are read-only through the public API.

Public endpoints:

Code
GET /api/v2/users
GET /api/v2/users/{id}

User lists use the shared pagination shape. Query options include:

• includeExternal=false when only internal users should be returned.
• includeGroups=true when the response must include group references.

There is no public v2 endpoint for direct user lookup by email.

Absences

Absences use plural /api/v2/absences paths:

Code
GET    /api/v2/absences
GET    /api/v2/absences/{id}
GET    /api/v2/absences/external-id/{externalId}
POST   /api/v2/absences
PUT    /api/v2/absences/{id}
PATCH  /api/v2/absences/{id}
DELETE /api/v2/absences/{id}

External-ID write paths are also available where documented in the API reference.

Absence create uses a structured request body:

Absence create request
{
  "externalId": "absence-123",
  "user": {
    "email": "editor@example.com",
    "supplierId": "supplier-7",
    "externalId": "user-42"
  },
  "period": {
    "fromDate": "2026-01-15",
    "fromTime": "09:00",
    "toDate": "2026-01-16",
    "toTime": "17:00"
  },
  "type": {
    "code": 3
  },
  "note": "Planned vacation"
}

In the user object, email and externalId identify the user, and supplierId is the organization-scoped supplier identifier used for external/freelancer users.

Important rules:

• POST /api/v2/absences returns 201 Created.
• PUT is full replacement and requires period and type.
• PATCH is presence-aware.
• externalId: null and note: null clear those fields where the API reference documents that behavior.
• period.fromDate and period.toDate are required when the period object is created or replaced.
• period.fromTime and period.toTime are optional time boundaries.
• delete operations return 204 No Content.

Absence lists support pagination plus filters such as fromDate, toDate, userId, userEmail, and type.

Shifts

Shifts are configuration data for work schedules.

External-ID clearing uses JSON null:

Code
{
  "externalId": null
}

For shift updates, an exactly empty external ID ("") is treated like null and clears the field. Whitespace-only external IDs are invalid, and non-empty external IDs are trimmed. For full replacement, name is required and cannot be null.

Shift Day Notes

Shift day notes use plural /notes paths:

Operation	v2 path
Read by shift ID and date	GET /api/v2/shifts/{shiftId}/notes/{date}
Read by external shift ID and date	GET /api/v2/shifts/external-id/{externalId}/notes/{date}
Create by shift ID	POST /api/v2/shifts/{shiftId}/notes
Create by external shift ID	POST /api/v2/shifts/external-id/{externalId}/notes
Replace by shift ID and date	PUT /api/v2/shifts/{shiftId}/notes/{date}
Replace by external shift ID and date	PUT /api/v2/shifts/external-id/{externalId}/notes/{date}

Create requests require date and note:

Code
{
  "date": "2026-01-15",
  "note": "Planning meeting before the morning shift"
}

Replace requests require date and note; the body date must match the path date.

Important rules:

• create returns 201 Created.
• duplicate notes return 409 Conflict.
• create can return 400 Bad Request when the date is not part of the shift schedule.
• note text must stay within the documented length limit.
• prefer persisted shift IDs when possible. External shift IDs are integration identifiers; use the v2 shift ID to target a specific shift.

Related Migration Notes

For v1 field mappings and path changes, see People And Scheduling Migration.