solarOSsolarOS Docs

Create a Service Appointment

Creates one interval-first Service Appointment for an accessible Work Order. scheduledStart, scheduledEnd, and timezone are required; durationMinutes is derived. Optional estimatedDurationMinutes is accepted only when it exactly matches the interval. Customer-facing windows must contain the exact scheduled interval. Assignment requires active same-organization schedulable Team Members (Service Resources) and a primary member included in the assigned set. Overlaps return structured warnings and do not block writes by themselves. Requires Idempotency-Key and service_appointments:write.

POST
/service-appointments

Creates one interval-first Service Appointment for an accessible Work Order. scheduledStart, scheduledEnd, and timezone are required; durationMinutes is derived. Optional estimatedDurationMinutes is accepted only when it exactly matches the interval. Customer-facing windows must contain the exact scheduled interval. Assignment requires active same-organization schedulable Team Members (Service Resources) and a primary member included in the assigned set. Overlaps return structured warnings and do not block writes by themselves. Requires Idempotency-Key and service_appointments:write.

Authorization

Authorization<token>

Organization API key. Format: Bearer sk_live_...

In: header

Request Body

application/json

JSON request payload for createServiceAppointment.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/service-appointments" \  -H "Content-Type: application/json" \  -d '{    "workOrderId": "work_order_123",    "scheduledStart": "2026-08-13T16:00:00Z",    "scheduledEnd": "2026-08-13T20:00:00Z",    "timezone": "America/Los_Angeles",    "assignedTeamMemberIds": [      "team_member_123"    ],    "primaryTeamMemberId": "team_member_123"  }'
{  "data": {},  "meta": {    "requestId": "string",    "version": "v1",    "timestamp": "2019-08-24T14:15:22Z",    "rateLimit": {      "limit": 0,      "remaining": 0,      "reset": 0    }  }}