Organization API

Create a Case

Creates a first-class service Case for an accessible Customer and linked Property. Requires Idempotency-Key. External References are created transactionally and conflicts return 409. Required scope: cases:write.

/api/v1/cases

Create a Case. Use an organization API key with cases:write. Check the response envelope and meta.requestId before triggering dependent workflow steps.

Required scopes

cases:writeIdempotency-Key required

Parameters

No path or query parameters.

Request body

objectrequired

Field	Type	Description
customerIdrequired	string	Optional unless marked required.
propertyIdrequired	string	Optional unless marked required.
systemId	string \| null	Optional unless marked required.
projectId	string \| null	Current project compatibility pointer. Changing or clearing it preserves prior Project memberships. Use Project.caseId to link/unlink membership.
subjectrequired	string	Optional unless marked required.
descriptionrequired	string	Optional unless marked required.
originrequired	PHONE \| EMAIL \| PORTAL \| MONITORING_ALERT \| IN_PERSON	Optional unless marked required.
severity	LOW \| MEDIUM \| HIGH \| URGENT	Optional unless marked required.
categoryrequired	string	Case Category key. Platform keys: HARDWARE_DEFECT, WORKMANSHIP, MONITORING, BILLING, OTHER. Organizations may add their own; list them with GET /case-categories.
status	OPEN \| TRIAGING \| IN_PROGRESS \| AWAITING_CUSTOMER \| AWAITING_VENDOR \| AWAITING_WORK \| RESOLVED \| CLOSED	CLOSED is the sole terminal status. Legacy RESOLVED input is accepted as CLOSED.
ownerId	string \| null	Active or draft same-organization Team Member id. When omitted, the API key default owner for this resource is used. Ownership cannot be changed through generic PATCH endpoints.
sourceServiceRequestId	string	Optional unless marked required.
slaResponseDueAt	string	Optional unless marked required.
externalReferences[]	array<object>	Optional unless marked required.
externalReferences[].externalSystemrequired	string	Optional unless marked required.
externalReferences[].externalObjectrequired	string	Optional unless marked required.
externalReferences[].externalIdrequired	string	Optional unless marked required.
externalReferences[].metadata	object	Optional unless marked required.

createcaseRequest

{
  "customerId": "customer_123",
  "propertyId": "property_123",
  "subject": "Inverter is offline",
  "description": "Monitoring data shows that the inverter stopped reporting this morning.",
  "origin": "MONITORING_ALERT",
  "severity": "MEDIUM",
  "category": "MONITORING"
}

Responses

201

Created Case envelope

#/components/schemas/CaseEnvelope

400

Validation, owner, or idempotency error