Industries
Sign Change Orders and Lien Waivers on Site
Print the change order number on the document, let the contractor describe the scope, and route it through the owner representative, contractor and owner.
A change order has to be approved and signed by several parties, often from a job site and a phone. Send it as an envelope with a prefilled number, a field for the contractor to describe the scope, and a fixed order of approvals.
Envelope shape
- Prefilled text. A
textplace printsChange Order CO-014on the document. The value comes from your system. See Text. - Multiline input. The contractor writes the scope in a
multiline_text_inputplace with aline_count, stored throughcapture_as: scope_note. See Multiline text input and Captures. - Three recipients. The owner’s representative is an
approverwith no places. The contractor and the owner aresignerrecipients, each with asignatureplace. - Metadata and topics.
project_idandchange_ordercorrelate the envelope with your project system. Theconstructionandchange_orderstopics group them.
Routing
The envelope uses sequential routing. The order is owner_rep, then contractor, then owner. Approvers and input places both require sequential routing. See Sequential signing and Send to an approver.
Webhooks to listen for
recipient.completed: fires after each step. Userecipient_keyandenvelope_metadata.change_orderto update the order’s status.recipient.rejected: the approver rejected the order. Flag it in your project system and send a revised one.envelope.completed: all three have finished. Mark the change order as executed.deliverable.generated: the signed order is ready to download and add to the project file.
Set up the endpoint as shown in Set up webhooks.
Compliance notes
This is general information, not legal advice. Whether an electronic signature is accepted on a change order or a lien waiver depends on your jurisdiction and your contract, and lien waiver forms are often prescribed by law, so have counsel review your documents and process.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Change Order CO-014 (sample)",
"message": "Please review the change order and sign.",
"routing": "sequential",
"metadata": {
"project_id": "proj_88",
"change_order": "CO-014"
},
"topics": [
"construction",
"change_orders"
],
"documents": [
{
"key": "change_order",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "co_number",
"page": 1,
"top": 100,
"left": 210
},
{
"place_key": "scope_note",
"page": 1,
"top": 125,
"left": 210
},
{
"place_key": "contractor_signature",
"page": 1,
"top": 172,
"left": 210
},
{
"place_key": "owner_signature",
"page": 1,
"top": 186,
"left": 220
}
],
"places": [
{
"key": "co_number",
"type": "text",
"value": "Change Order CO-014"
},
{
"key": "scope_note",
"type": "multiline_text_input",
"recipient_key": "contractor",
"prompt": "Scope of change",
"width": 300,
"line_count": 3,
"capture_as": "scope_note"
},
{
"key": "contractor_signature",
"type": "signature",
"recipient_key": "contractor"
},
{
"key": "owner_signature",
"type": "signature",
"recipient_key": "owner"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "owner_rep",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "contractor",
"name": "John Smith",
"email": "john.smith@example.com"
},
{
"type": "signer",
"key": "owner",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Change Order CO-014 (sample)",
"message": "Please review the change order and sign.",
"routing": "sequential",
"metadata": {
"project_id": "proj_88",
"change_order": "CO-014"
},
"topics": [
"construction",
"change_orders"
],
"documents": [
{
"key": "change_order",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "co_number",
"page": 1,
"top": 100,
"left": 210
},
{
"place_key": "scope_note",
"page": 1,
"top": 125,
"left": 210
},
{
"place_key": "contractor_signature",
"page": 1,
"top": 172,
"left": 210
},
{
"place_key": "owner_signature",
"page": 1,
"top": 186,
"left": 220
}
],
"places": [
{
"key": "co_number",
"type": "text",
"value": "Change Order CO-014"
},
{
"key": "scope_note",
"type": "multiline_text_input",
"recipient_key": "contractor",
"prompt": "Scope of change",
"width": 300,
"line_count": 3,
"capture_as": "scope_note"
},
{
"key": "contractor_signature",
"type": "signature",
"recipient_key": "contractor"
},
{
"key": "owner_signature",
"type": "signature",
"recipient_key": "owner"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "owner_rep",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "contractor",
"name": "John Smith",
"email": "john.smith@example.com"
},
{
"type": "signer",
"key": "owner",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Change Order CO-014 (sample)",
"message": "Please review the change order and sign.",
"routing": "sequential",
"metadata": {
"project_id": "proj_88",
"change_order": "CO-014"
},
"topics": [
"construction",
"change_orders"
],
"documents": [
{
"key": "change_order",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "co_number",
"page": 1,
"top": 100,
"left": 210
},
{
"place_key": "scope_note",
"page": 1,
"top": 125,
"left": 210
},
{
"place_key": "contractor_signature",
"page": 1,
"top": 172,
"left": 210
},
{
"place_key": "owner_signature",
"page": 1,
"top": 186,
"left": 220
}
],
"places": [
{
"key": "co_number",
"type": "text",
"value": "Change Order CO-014"
},
{
"key": "scope_note",
"type": "multiline_text_input",
"recipient_key": "contractor",
"prompt": "Scope of change",
"width": 300,
"line_count": 3,
"capture_as": "scope_note"
},
{
"key": "contractor_signature",
"type": "signature",
"recipient_key": "contractor"
},
{
"key": "owner_signature",
"type": "signature",
"recipient_key": "owner"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "owner_rep",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "contractor",
"name": "John Smith",
"email": "john.smith@example.com"
},
{
"type": "signer",
"key": "owner",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Change Order CO-014 (sample)",
"label": null,
"message": "Please review the change order and sign.",
"status": "processing",
"attestation": "none",
"language": "en",
"mode": "test",
"routing": "sequential",
"timezone": "UTC",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"snapshot_url": null,
"branding": {
"logo": null,
"accent_color": "#2463EB",
"email": {
"footer": null,
"logo_position": "left",
"from": "noreply@signatureapi.com"
}
},
"deliverable": {
"id": "del_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"name": null,
"status": "pending",
"type": "standard",
"url": null,
"password": null,
"created_at": "2026-11-02T14:03:11.000Z",
"generated_at": null,
"timezone": "UTC",
"language": "en",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"included_documents": [
"change_order"
]
},
"metadata": {
"project_id": "proj_88",
"change_order": "CO-014"
},
"sender": {
"name": "Acme Corp Legal",
"email": "legal@acme.example",
"organization": "Acme Corp"
},
"captures": {
"scope_note": null
},
"documents": [
{
"id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "change_order",
"title": null,
"page_count": 1,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"page": 1,
"top": 100,
"left": 210,
"place_key": "co_number"
},
{
"page": 1,
"top": 125,
"left": 210,
"place_key": "scope_note"
},
{
"page": 1,
"top": 172,
"left": 210,
"place_key": "contractor_signature"
},
{
"page": 1,
"top": 186,
"left": 220,
"place_key": "owner_signature"
}
],
"places": [
{
"key": "co_number",
"type": "text",
"font_color": "#000000",
"font_size": 12,
"value": "Change Order CO-014"
},
{
"key": "scope_note",
"type": "multiline_text_input",
"recipient_key": "contractor",
"capture_as": "scope_note",
"hint": null,
"prompt": "Scope of change",
"requirement": "required",
"font_size": 12,
"width": 300,
"line_count": 3,
"line_height": 12
},
{
"key": "contractor_signature",
"type": "signature",
"recipient_key": "contractor",
"height": 60
},
{
"key": "owner_signature",
"type": "signature",
"recipient_key": "owner",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "approver",
"key": "owner_rep",
"email": "alex.chen@example.com",
"name": "Alex Chen",
"ceremony": {
"authentication": [
{
"type": "email_link",
"subject_override": null,
"message_override": null
}
],
"embeddable_in": [],
"redirect_url": null,
"redirect_delay": 3,
"url": null,
"url_variant": "standard"
},
"ceremony_creation": "automatic",
"delivery_type": "none",
"status": "pending",
"status_updated_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
},
{
"id": "re_OcsAUqEe6a6eEqUAscOC2u",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "contractor",
"email": "john.smith@example.com",
"name": "John Smith",
"ceremony": {
"authentication": [
{
"type": "email_link",
"subject_override": null,
"message_override": null
}
],
"embeddable_in": [],
"redirect_url": null,
"redirect_delay": 3,
"url": null,
"url_variant": "standard"
},
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": [
"typed",
"drawn"
],
"status": "awaiting",
"status_updated_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
},
{
"id": "re_VjzHbxLlDhDlLxbHzjVJ91",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "owner",
"email": "jane.doe@example.com",
"name": "Jane Doe",
"ceremony": {
"authentication": [
{
"type": "email_link",
"subject_override": null,
"message_override": null
}
],
"embeddable_in": [],
"redirect_url": null,
"redirect_delay": 3,
"url": null,
"url_variant": "standard"
},
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": [
"typed",
"drawn"
],
"status": "awaiting",
"status_updated_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
}
],
"topics": [
"construction",
"change_orders"
],
"created_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
}{
"type": "https://signatureapi.com/docs/v1/errors/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The request body contains validation errors.",
"errors": [
"recipients[0].email must be a valid email address"
]
}Errors every call can return are in Errors and Authentication.