--- title: "[beta] Create a batch of maintenance estimates" method: POST path: "/maintenance/estimates/batch" tags: ["Beta APIs"] --- # \[beta\] Create a batch of maintenance estimates `POST /maintenance/estimates/batch` ## Request - Base URL: `https://api.samsara.com` - URL: `https://api.samsara.com/maintenance/estimates/batch` - Auth: HTTP bearer Create 1–10 unapproved priced recommendations or vendor quotes in one request, limited to 3000000 raw JSON bytes. The batch is non-atomic: each create is independently authorized and validated, and successful writes remain committed when another item fails. Structural request errors return 400 before execution; exceeding the count or byte bound returns 413. Item business errors are returned in input order alongside successes, under HTTP 200. The rate limit applies to batch requests, not individual estimates. Approval, denial, award and attachments use their existing separate operations. Retry failed items only; reconcile ambiguous outcomes by stable external IDs through GET before retrying, because ordinary quote creation is not automatically replayed. Rate limit: 100 requests/min (learn more about rate limits here). To use this endpoint, select **Write Work Orders** under the Work Orders category when creating or editing an API token. Learn More. **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team. ## Query parameters - `includeExternalIds` boolean ## Request body - MaintenanceEstimatesCreateMaintenanceEstimatesBatchRequestBody: Non-atomic batch of 1–10 priced recommendations or vendor quotes. Raw JSON is limited to 3000000 bytes; existing per-quote limits also apply. - `estimates` MaintenanceEstimateBatchCreateInputRequestBody[], required: Estimates to create, in response order. Maximum 10; an excess returns HTTP 413. - `approvalStatus` 'unapproved': Defaults to unapproved. Batch ingestion does not approve, deny or award; use individual updates for lifecycle changes. Valid values: `unapproved` - `estimateType` 'expectedCost' | 'vendorQuote': Recommendation or vendor quote. Defaults to vendorQuote when omitted. expectedCost requires an externally managed work order and must be created unapproved; lineItems and tax remain required. Valid values: `expectedCost`, `vendorQuote` - `externalIds` object: Estimate external identifiers. Responses include these only when includeExternalIds=true; default omitted. - `externalRequest` MaintenanceEstimateExternalRequestInputRequestBody: Optional provider metadata. Every child is optional. PATCH replaces the whole object, null or an empty object clears it, and omission preserves it. Nonempty provider metadata requires an actual quote or an active selected recommendation. - `actionUrl` string: Optional provider URL. Nonempty values must be HTTPS without embedded credentials, at most 2048 bytes; empty strings are accepted. - `externalRequestId` string: Optional provider request reference, not an estimate alias or idempotency key. Empty strings are accepted. - `externalSystem` string: Optional external provider name; empty strings are accepted. - `message` string: Optional display message; empty strings are accepted. - `lineItems` MaintenanceEstimateLineInputRequestBody[], required: Complete set of 1 to 200 priced lines when supplied. - `amount` MaintenanceEstimateMoneyRequestBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `costType` 'labor' | 'parts': Optional classification of the entire line. Labor assigns all cost to labor; parts assigns all cost to parts. Omission leaves a new or replacement line unclassified; it does not infer a type from description. Valid values: `labor`, `parts` - `description` string: Vendor's quote text, at most 2000 Unicode characters. - `id` string: Existing line ID when retaining a line during PATCH. - `quantity` number: Quantity or labor hours, greater than zero with at most two fractional digits. When supplied, unitRate is also required. Omitted when actual quantity is unknown. - `serviceTaskId` string: Associated service-task instance belonging to this WO. - `unitRate` MaintenanceEstimateUnitRateRequestBody: Price per quantity unit in the organization's currency. Rates can include fractional cents; round the extended line amount once to cents. - `amount` string, required: Nonnegative decimal unit price, with up to six fractional digits. Signs, exponents and grouping separators are not accepted. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: Three-letter ISO 4217 currency code. Must match the organization's current currency and the line amount. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `notes` string: Notes, at most 4000 Unicode characters. - `quotedAtTime` string, date-time: Actual quote timestamp. Omit if the source only has a date; do not invent a time or offset. - `supersedesEstimateId` string: Same-WO/vendor denied estimate superseded by this quote. - `tax` MaintenanceEstimateMoneyRequestBody, required: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `vendorId` string, required: Same-org vendor location UUID or external ID. Resolve the location via GET /fleet/maintenance/vendor-locations. - `workOrderId` string, required: Same-org numeric work order ID. ## Response `200` OK response. - MaintenanceEstimatesCreateMaintenanceEstimatesBatchResponseBody - `requestId` string, uuid, required: UUID identifying this batch request. - `responses` MaintenanceEstimateBatchItemResponseResponseBody[], required: One outcome per input, in the same order. Successful writes remain committed when another item fails. - `data` MaintenanceEstimateObjectResponseBody: A priced vendor recommendation or quote for one work order. - `approvalSource` 'unknown' | 'none' | 'policy' | 'samsara', required: Authority for the current approval state. Defaults to none. Valid values: `unknown`, `none`, `policy`, `samsara` - `approvalStatus` 'unknown' | 'unapproved' | 'pending' | 'approved' | 'denied' | 'cancelled', required: Approval state. Vendor quotes default to unapproved; expectedCost recommendations report unknown until conversion, or cancelled after cancellation. Approval and award are separate operations. Valid values: `unknown`, `unapproved`, `pending`, `approved`, `denied`, `cancelled` - `attachments` MaintenanceEstimateAttachmentResponseBody[], required: Quote documents. API additions enforce a 50-file WO admission limit against observed files and pending API reservations. - `createdAtTime` string, date-time, required: Time the attachment was created. - `id` string, required: Stable attachment ID. - `name` string, required: Original or generated filename. - `processingStatus` 'unknown' | 'processing' | 'finished', required: Attachment availability. Defaults to processing until a validated download is available; unknown when availability cannot be determined. Valid values: `unknown`, `processing`, `finished` - `updatedAtTime` string, date-time, required: Latest attachment change; initially equal to creation time. - `url` string, uri: Temporary download URL; present only when processingStatus is finished. - `urlExpiresAt` string, date-time: Expiration of the temporary download URL; present only with url. - `createdAtTime` string, date-time, required: Server creation time. - `estimateType` 'unknown' | 'expectedCost' | 'vendorQuote', required: Whether this estimate is a recommendation or a vendor quote. Omitted create values default to vendorQuote. Unknown represents an unrecognized type. Valid values: `unknown`, `expectedCost`, `vendorQuote` - `externalIds` object: Estimate external identifiers. Responses include these only when includeExternalIds=true; default omitted. - `externalRequest` MaintenanceEstimateExternalRequestResponseBody: Provider request details. This metadata does not create a request or change approval or award status. - `actionUrl` string, uri: HTTPS provider URL without embedded credentials; at most 2048 bytes. - `externalRequestId` string: Provider request reference, not an estimate lookup alias or idempotency key; at most 200 characters. - `externalSystem` string: External provider name; at most 100 characters. - `message` string: Optional display message; at most 500 characters. - `id` string, required: Stable estimate ID. - `isAwarded` boolean, required: Whether this exact vendor quote has been awarded for the WO. Defaults to false; recommendation selection and approval do not award. - `lineItems` MaintenanceEstimateLineItemResponseBody[], required: Up to 200 priced lines; incomplete dashboard quotes may have no lines. - `amount` MaintenanceEstimateMoneyResponseBody, required: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `costType` 'unknown' | 'labor' | 'parts': Whether the entire line is labor or parts. Omitted when classification is absent or mixed; unknown represents an unrecognized classification. No classification is inferred from description. Valid values: `unknown`, `labor`, `parts` - `description` string: Vendor quote text; retained even when serviceTaskId is supplied. Maximum 2000 Unicode characters. - `id` string, required: Server-generated line ID. - `quantity` number: Quantity or labor hours, greater than zero with at most two fractional digits. When supplied, unitRate is also required. Omitted when actual quantity is unknown. - `serviceTaskId` string: Associated WO service-task instance ID; not a task catalog ID. - `unitRate` MaintenanceEstimateUnitRateResponseBody: Price per quantity unit in the organization's currency. Rates can include fractional cents; round the extended line amount once to cents. - `amount` string, required: Nonnegative decimal unit price, with up to six fractional digits. Signs, exponents and grouping separators are not accepted. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: Three-letter ISO 4217 currency code. Must match the organization's current currency and the line amount. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `notes` string: Additional notes, at most 4000 Unicode characters. - `quotedAtTime` string, date-time: Actual instant the vendor issued the quote; omit when only a date is known. - `subtotal` MaintenanceEstimateMoneyResponseBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `supersededByEstimateId` string: Successor estimate; a superseded quote is historical. - `supersedesEstimateId` string: Previous denied estimate replaced by this new quote. - `tax` MaintenanceEstimateMoneyResponseBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `total` MaintenanceEstimateMoneyResponseBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `updatedAtTime` string, date-time, required: Latest public content or lifecycle change. - `vendorId` string: Vendor location ID. Resolve the location via GET /fleet/maintenance/vendor-locations. - `version` integer, required: Monotonic change counter including lifecycle and attachment updates. - `workOrderId` string, required: Owning numeric work order ID. - `message` string: Caller-safe error message; present only on failure. - `status` integer, required: HTTP-style result code. 200 on success. ## Other responses - `401`: Unauthorized response. - `404`: Not Found response. - `405`: Method Not Allowed response. - `413`: Content Too Large response. - `429`: Too Many Requests response. - `500`: Internal Server Error response. - `501`: Not Implemented response. - `502`: Bad Gateway response. - `503`: Service Unavailable response. - `504`: Gateway Timeout response. - `default`: Bad Request response. --- [API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)