Email a change order to the customer
const url = 'https://app.buildworkpro.com/api/v1/change-orders/1/send';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"templateId":1,"recipientEmails":["hello@example.com"],"cc":["hello@example.com"],"bcc":["hello@example.com"],"subject":"example","body":"example","requestSignature":false,"signerEmail":"hello@example.com","signerName":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.buildworkpro.com/api/v1/change-orders/1/send \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "templateId": 1, "recipientEmails": [ "hello@example.com" ], "cc": [ "hello@example.com" ], "bcc": [ "hello@example.com" ], "subject": "example", "body": "example", "requestSignature": false, "signerEmail": "hello@example.com", "signerName": "example" }'Emails the change order PDF to the given recipients and marks it sent. Same delivery pipeline as the product’s send action. Requires change_orders:send. Set requestSignature to true to include a signing link in that same email. That also requires the signatures:send scope, a signer name, and e-signature to be enabled for the organization. The signer email defaults to the project contact, then the first To address. Approved, rejected, and voided change orders cannot be sent for signature; a plain email of those change orders is still allowed. The response includes signatureRequested and, when a request was created, signatureRequestId. It never includes a signing URL or recipient token.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”Header Parameters
Section titled “ Header Parameters ”Idempotent retry key for mutating operations. The first request with a given key executes normally and BuildWorkPro caches the response. Replaying the same key with the same request body (method + path + JSON body, SHA-256 hashed) returns the cached response without re-executing the mutation. Replaying with a DIFFERENT body returns 409 idempotency_key_reused. The cache TTL is 24 hours; after expiry the key is treated as a new operation. Keys are tenant-scoped. Recommended: a fresh UUID v4 per logical operation.
Request Body
Section titled “ Request Body ”object
When true, this send also starts an e-signature and the email includes the signing link. Defaults to false. Also requires the signatures:send scope and a signer name.
Signer email. Defaults to the project contact’s email, then the first To address. Must be one of the recipients.
Signer name. Required when requestSignature is true.
Responses
Section titled “ Responses ”Sent
object
object
True when this send created an e-signature request.
Id of the signature request created by this send. Never a signing URL or recipient token.
object
Server-generated request identifier
object
Opaque cursor for the next page; null when no more results
Whether more pages are available after this one
Items in this page
Example generated
{ "data": { "success": true, "messageId": "example", "recipientCount": 1, "changeOrderId": 1, "signatureRequested": true, "signatureRequestId": 1 }, "meta": { "request_id": "example", "pagination": { "cursor": "example", "has_more": true, "count": 1 } }}Error
object
URL identifying the problem type
Short human-readable summary
HTTP status code
Human-readable explanation
Server-generated request identifier
Validation error array (422 only)
object
Field path that failed validation
Validation error code
Human-readable validation message
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "detail": "example", "request_id": "example", "errors": [ { "field": "example", "code": "example", "message": "example" } ]}Error
object
URL identifying the problem type
Short human-readable summary
HTTP status code
Human-readable explanation
Server-generated request identifier
Validation error array (422 only)
object
Field path that failed validation
Validation error code
Human-readable validation message
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "detail": "example", "request_id": "example", "errors": [ { "field": "example", "code": "example", "message": "example" } ]}Error
object
URL identifying the problem type
Short human-readable summary
HTTP status code
Human-readable explanation
Server-generated request identifier
Validation error array (422 only)
object
Field path that failed validation
Validation error code
Human-readable validation message
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "detail": "example", "request_id": "example", "errors": [ { "field": "example", "code": "example", "message": "example" } ]}Error
object
URL identifying the problem type
Short human-readable summary
HTTP status code
Human-readable explanation
Server-generated request identifier
Validation error array (422 only)
object
Field path that failed validation
Validation error code
Human-readable validation message
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "detail": "example", "request_id": "example", "errors": [ { "field": "example", "code": "example", "message": "example" } ]}Error
object
URL identifying the problem type
Short human-readable summary
HTTP status code
Human-readable explanation
Server-generated request identifier
Validation error array (422 only)
object
Field path that failed validation
Validation error code
Human-readable validation message
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "detail": "example", "request_id": "example", "errors": [ { "field": "example", "code": "example", "message": "example" } ]}Error
object
URL identifying the problem type
Short human-readable summary
HTTP status code
Human-readable explanation
Server-generated request identifier
Validation error array (422 only)
object
Field path that failed validation
Validation error code
Human-readable validation message
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "detail": "example", "request_id": "example", "errors": [ { "field": "example", "code": "example", "message": "example" } ]}