---
title: "Sign Change Orders and Lien Waivers on Site"
description: "Print the change order number on the document, let the contractor describe the scope, and route it through the owner representative, contractor and owner."
canonical: "https://signatureapi.com/docs/use-cases/construction-change-orders"
source: "https://signatureapi.com/docs/use-cases/construction-change-orders.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:55Z"
---

# 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.

_Last verified against API version 1.18.0._

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 `text` place prints `Change Order CO-014` on the document. The value comes from your system. See [Text](https://signatureapi.com/docs/api/resources/places/text).
- **Multiline input.** The contractor writes the scope in a `multiline_text_input` place with a `line_count`, stored through `capture_as: scope_note`. See [Multiline text input](https://signatureapi.com/docs/api/resources/places/multiline-text-input) and [Captures](https://signatureapi.com/docs/api/resources/envelopes/captures).
- **Three recipients.** The owner's representative is an `approver` with no places. The contractor and the owner are `signer` recipients, each with a `signature` place.
- **Metadata and topics.** `project_id` and `change_order` correlate the envelope with your project system. The `construction` and `change_orders` topics 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](https://signatureapi.com/docs/api/guides/how-to/sequential-signing) and [Send to an approver](https://signatureapi.com/docs/api/guides/how-to/send-to-approver).

## Webhooks to listen for

- [`recipient.completed`](https://signatureapi.com/docs/api/resources/events/recipient-events): fires after each step. Use `recipient_key` and `envelope_metadata.change_order` to update the order's status.
- [`recipient.rejected`](https://signatureapi.com/docs/api/resources/events/recipient-events): the approver rejected the order. Flag it in your project system and send a revised one.
- [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events): all three have finished. Mark the change order as executed.
- [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events): the signed order is ready to download and add to the project file.

Set up the endpoint as shown in [Set up webhooks](https://signatureapi.com/docs/api/guides/how-to/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.

### Example: Default

Change Order CO-014 (sample).

```http
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"
    }
  ]
}
```

Response 201 Created:

```json
{
  "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
}
```

Response 422 Unprocessable Content:

```json
{
  "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 that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
