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.
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.
Create a Service Appointment. Use an organization API key with service_appointments:write. Check the response envelope and meta.requestId before triggering dependent workflow steps.
Required scopes
Parameters
No path or query parameters.
Request body
| Field | Type | Description |
|---|---|---|
| workOrderIdrequired | string | Optional unless marked required. |
| scheduledStartrequired | string | Optional unless marked required. |
| scheduledEndrequired | string | Optional unless marked required. |
| timezonerequired | string | Optional unless marked required. |
| customerWindowStart | string | null | Optional unless marked required. |
| customerWindowEnd | string | null | Optional unless marked required. |
| assignedTeamMemberIds[]required | array<string> | Optional unless marked required. |
| primaryTeamMemberIdrequired | string | Optional unless marked required. |
| notes | string | null | Optional unless marked required. |
| schedulingConfidence | TENTATIVELY_SCHEDULED | CONFIDENTLY_SCHEDULED | CONFIRMED | Optional unless marked required. |
| estimatedDurationMinutes | integer | Optional unless marked required. |
{
"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"
}Responses
Created Service Appointment envelope with warnings
#/components/schemas/OrgApiResourceEnvelope
Validation or idempotency error
#/components/schemas/OrgApiError
Missing or invalid organization API key
#/components/schemas/OrgApiError
Organization billing access or an endpoint-specific business quota denied the request
#/components/schemas/OrgApiError
Missing required scope: service_appointments:write
#/components/schemas/OrgApiError
Work Order not found
#/components/schemas/OrgApiError
Idempotency conflict
#/components/schemas/OrgApiError
Rate limit exceeded
#/components/schemas/OrgApiError
Errors
Static examples
curl -X POST "$SOLAROS_BASE_URL/api/v1/service-appointments" \
-H "Authorization: Bearer $SOLAROS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SOLAROS_IDEMPOTENCY_KEY" \
--data '{"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"}'