Create an External Reference
Creates or replays one tenant-scoped External Reference for a solarOS resource. Replays return the existing reference when the tuple already points at the same resource; conflicts return 409. Required scope: external_references:write.
Creates or replays one tenant-scoped External Reference for a solarOS resource. Replays return the existing reference when the tuple already points at the same resource; conflicts return 409. Required scope: external_references:write.
Create an External Reference. Use an organization API key with external_references: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 |
|---|---|---|
| resourceTyperequired | string | Optional unless marked required. |
| resourceIdrequired | string | Optional unless marked required. |
| externalSystemrequired | string | Optional unless marked required. |
| externalObjectrequired | string | Optional unless marked required. |
| externalIdrequired | string | Optional unless marked required. |
| metadata | object | Optional unless marked required. |
{
"resourceType": "WorkOrder",
"resourceId": "work_order_123",
"externalSystem": "salesforce",
"externalObject": "WorkOrder",
"externalId": "0WO123"
}Responses
Existing matching External Reference envelope
#/components/schemas/OrgApiResourceEnvelope
External Reference created envelope
#/components/schemas/OrgApiResourceEnvelope
Invalid External Reference payload
#/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 external_references:write scope
#/components/schemas/OrgApiError
External Reference tuple already points elsewhere
#/components/schemas/OrgApiError
Rate limit exceeded
#/components/schemas/OrgApiError
Errors
Static examples
curl -X POST "$SOLAROS_BASE_URL/api/v1/external-references" \
-H "Authorization: Bearer $SOLAROS_API_KEY" \
-H "Content-Type: application/json" \
--data '{"resourceType":"WorkOrder","resourceId":"work_order_123","externalSystem":"salesforce","externalObject":"WorkOrder","externalId":"0WO123"}'