Create an Opportunity
Creates an Opportunity for an accessible Customer. propertyId is optional for external CRM imports that do not yet have a solarOS Property mapping. Stage changes do not create hidden downstream records. Without originatorId, the owner is credited with bringing the sale in. Requires Idempotency-Key.
Creates an Opportunity for an accessible Customer. propertyId is optional for external CRM imports that do not yet have a solarOS Property mapping. Stage changes do not create hidden downstream records. Without originatorId, the owner is credited with bringing the sale in. Requires Idempotency-Key.
Create an Opportunity. Use an organization API key with opportunities: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 |
|---|---|---|
| namerequired | string | Optional unless marked required. |
| customerIdrequired | string | Optional unless marked required. |
| propertyId | string | null | Optional unless marked required. |
| value | string | number | null | Optional unless marked required. |
| stage | NEW | PROPOSAL | NEGOTIATION | CLOSED_WON | CLOSED_LOST | Optional unless marked required. |
| expectedCloseDate | string | null | Optional unless marked required. |
| 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. |
| originatorId | string | null | The active or draft same-organization Team Member credited with bringing this sale in. When omitted, the owner is credited. |
| notes | string | null | Optional unless marked required. |
| customFields | object | Field Values keyed by savedIdentity from GET /api/v1/schema. |
| 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. |
{
"customerId": "customer_123",
"propertyId": "property_123",
"name": "Residential solar install",
"stage": "PROPOSAL",
"value": "42500",
"expectedCloseDate": "2026-09-15"
}Responses
Opportunity envelope
#/components/schemas/OrgApiResourceEnvelope
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: opportunities:write
#/components/schemas/OrgApiError
Customer or Property not found
#/components/schemas/OrgApiError
Rate limit exceeded
#/components/schemas/OrgApiError
Errors
Static examples
curl -X POST "$SOLAROS_BASE_URL/api/v1/opportunities" \
-H "Authorization: Bearer $SOLAROS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SOLAROS_IDEMPOTENCY_KEY" \
--data '{"customerId":"customer_123","propertyId":"property_123","name":"Residential solar install","stage":"PROPOSAL","value":"42500","expectedCloseDate":"2026-09-15"}'