---
title: "Onboard Drivers and Collect Delivery Acknowledgements"
description: "Create a driver agreement with a short signing link that you send by SMS through your own channel, with no signing email and no deliverable email."
canonical: "https://signatureapi.com/docs/use-cases/logistics-drivers"
source: "https://signatureapi.com/docs/use-cases/logistics-drivers.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:55Z"
---

# Onboard Drivers and Collect Delivery Acknowledgements

Create a driver agreement with a short signing link that you send by SMS through your own channel, with no signing email and no deliverable email.

_Last verified against API version 1.18.0._

Drivers are on the road and often have no work email. They have a phone. This envelope returns a short signing link in the create response, so your dispatch system can text it to the driver. The link opens the signing page directly.

## Envelope shape

- **Inline ceremony with `custom` authentication.** The `ceremony` object sits on the recipient. Your dispatch system vouches for the driver: `provider` and `data` appear in the audit log. Here `data` records the channel and an opaque `driver_ref`. See [Custom authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom).
- **Short URL.** `url_variant: "short"` makes a link that fits in an SMS. With `custom` first, SignatureAPI returns the URL in the response and sends no email. See [Send signing links via SMS](https://signatureapi.com/docs/api/guides/use-cases/sms-signing-link).
- **`delivery_type: "none"`.** SignatureAPI does not email the signed documents to the driver. You store or distribute them. See [Signer](https://signatureapi.com/docs/api/resources/recipients/signer).
- **Required safety checkbox.** The driver must check `safety_policy`, then initial and sign. `capture_as` stores the checkbox value in the envelope `captures`. See [Checkbox](https://signatureapi.com/docs/api/resources/places/checkbox) and [Captures](https://signatureapi.com/docs/api/resources/envelopes/captures).

## Routing

There is one signer, so the envelope uses the default `sequential` routing. The checkbox is a form place, and form places need sequential routing.

## Webhooks to listen for

- [`recipient.accessed`](https://signatureapi.com/docs/api/resources/events/recipient-events): the driver opened the link. Use it to confirm the text message arrived.
- [`recipient.completed`](https://signatureapi.com/docs/api/resources/events/recipient-events): the driver signed. Read `envelope_metadata.driver_ref` to mark the driver as onboarded in your system.
- [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events): all recipients have finished.
- [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events): the signed agreement and audit log are ready. Download and store them, because nothing is emailed to the driver.

## Compliance notes

This is general information, not legal advice. Employment and contractor requirements for drivers vary by jurisdiction, so have counsel review your agreement and process. A short signing link is a bearer credential: anyone who has it can open the ceremony. Send it only to the driver, do not log it, and keep personal data out of `metadata`, which appears in webhook payloads. SignatureAPI records the `provider` and `data` you send. It does not check them, so they must be enough for you to show how you identified the driver.

### Example: Default

Driver Agreement (sample).

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Driver Agreement (sample)",
  "metadata": {
    "driver_ref": "drv_314"
  },
  "topics": [
    "logistics",
    "driver_onboarding"
  ],
  "documents": [
    {
      "key": "driver_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "safety_policy",
          "page": 1,
          "top": 140,
          "left": 210
        },
        {
          "place_key": "driver_initials",
          "page": 1,
          "top": 250,
          "left": 72
        },
        {
          "place_key": "driver_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "safety_policy",
          "type": "checkbox",
          "recipient_key": "driver",
          "requirement": "required",
          "capture_as": "safety_policy"
        },
        {
          "key": "driver_initials",
          "type": "initials",
          "recipient_key": "driver",
          "height": 30
        },
        {
          "key": "driver_signature",
          "type": "signature",
          "recipient_key": "driver"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "driver",
      "name": "Maria Garcia",
      "email": "maria.garcia@example.com",
      "delivery_type": "none",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "Acme Dispatch SMS",
            "data": {
              "channel": "sms",
              "driver_ref": "drv_314"
            }
          }
        ],
        "url_variant": "short"
      }
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Driver Agreement (sample)",
  "label": null,
  "message": null,
  "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": [
      "driver_agreement"
    ]
  },
  "metadata": {
    "driver_ref": "drv_314"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {
    "safety_policy": false
  },
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "driver_agreement",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "page": 1,
          "top": 140,
          "left": 210,
          "place_key": "safety_policy"
        },
        {
          "page": 1,
          "top": 250,
          "left": 72,
          "place_key": "driver_initials"
        },
        {
          "page": 1,
          "top": 172,
          "left": 210,
          "place_key": "driver_signature"
        }
      ],
      "places": [
        {
          "key": "safety_policy",
          "type": "checkbox",
          "recipient_key": "driver",
          "height": 20,
          "symbol": "check",
          "capture_as": "safety_policy",
          "requirement": "required"
        },
        {
          "key": "driver_initials",
          "type": "initials",
          "recipient_key": "driver",
          "height": 30
        },
        {
          "key": "driver_signature",
          "type": "signature",
          "recipient_key": "driver",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "driver",
      "email": "maria.garcia@example.com",
      "name": "Maria Garcia",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "Acme Dispatch SMS",
            "data": {
              "channel": "sms",
              "driver_ref": "drv_314"
            }
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": "https://sign.signatureapi.com/s/GYxHhFr7kYziDs9E",
        "url_variant": "short"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "none",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "status": "pending",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "logistics",
    "driver_onboarding"
  ],
  "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.
