Organization API

Create a Material Request

Creates a Material Request for a project-contained Work Order (workOrderId) or for a Project (projectId), with optional line items and order details. Like a request made in solarOS, it gets a Record Number and a step on the Project so it shows in the Project's materials. A status other than PENDING moves that step as it would in solarOS. pickupLocationId must be from GET /pickup-locations, and a line's productId must be a Product in this organization's catalog. estimatedCost is computed from the line items. Requires Idempotency-Key and material_reqs:write.

/api/v1/material-reqs

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

Required scopes

material_reqs:writeIdempotency-Key required

Parameters

No path or query parameters.

Request body

objectrequired

Field	Type	Description
workOrderId	string	A project-contained Work Order. The request also shows on its Project.
projectId	string	The Project, for a request that isn't for one Work Order. With workOrderId it must be the Work Order's Project.
status	PENDING \| ORDERED \| PARTIALLY_RECEIVED \| RECEIVED \| READY_FOR_PICKUP \| PICKED_UP \| CANCELLED	A change moves the request's project step as it would in solarOS. PICKED_UP stamps pickedUpAt and marks pending and ordered line items picked up.
neededByDate	string \| null	A day: YYYY-MM-DD, saved as midnight UTC the way solarOS's date pickers save it, or an ISO 8601 date-time.
vendorName	string \| null	Optional unless marked required.
vendorOrderRef	string \| null	The vendor's order or PO number.
orderedDate	string \| null	A day: YYYY-MM-DD, saved as midnight UTC the way solarOS's date pickers save it, or an ISO 8601 date-time.
expectedDate	string \| null	A day: YYYY-MM-DD, saved as midnight UTC the way solarOS's date pickers save it, or an ISO 8601 date-time.
receivedDate	string \| null	A day: YYYY-MM-DD, saved as midnight UTC the way solarOS's date pickers save it, or an ISO 8601 date-time.
actualCost	number \| null	Optional unless marked required.
pickupLocationId	string \| null	An id from GET /pickup-locations.
notes	string \| null	Optional unless marked required.
lineItems[]	array<object>	Optional unless marked required.
lineItems[].namerequired	string	Optional unless marked required.
lineItems[].quantityrequired	integer	Optional unless marked required.
lineItems[].unit	string	Defaults to each.
lineItems[].productId	string \| null	A Product in this organization's catalog.
lineItems[].description	string \| null	Optional unless marked required.
lineItems[].unitCost	number \| null	Optional unless marked required.

creatematerialreqRequest

{
  "workOrderId": "work_order_123",
  "status": "ORDERED",
  "vendorName": "CED Greentech",
  "vendorOrderRef": "SO-88123",
  "orderedDate": "2026-10-29",
  "neededByDate": "2026-11-04",
  "pickupLocationId": "location_123",
  "lineItems": [
    {
      "name": "Powerwall 3",
      "quantity": 1,
      "unitCost": 9850
    }
  ]
}

Responses

201

Created Material Request envelope

#/components/schemas/MaterialRequestEnvelope

400

Validation error: neither workOrderId nor projectId, a projectId that is not the Work Order's Project, a pickup Location that is archived or not open for pickup, or a missing Idempotency-Key