---
title: "Send Offer Letters From Your ATS"
description: "Merge candidate data into a DOCX offer letter, route it through the hiring manager to the candidate, and update your ATS from webhooks when the candidate signs."
canonical: "https://signatureapi.com/docs/use-cases/hr-offer-letters"
source: "https://signatureapi.com/docs/use-cases/hr-offer-letters.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:55Z"
---

# Send Offer Letters From Your ATS

Merge candidate data into a DOCX offer letter, route it through the hiring manager to the candidate, and update your ATS from webhooks when the candidate signs.

_Last verified against API version 1.18.0._

Your applicant tracking system (ATS) knows the candidate's name, title, start date and salary. Your offer letter is a Word file. Instead of copying values by hand, keep one DOCX template with merge fields and send the values as data. SignatureAPI fills the template, adds the signature place and routes the letter.

## Envelope shape

- **One DOCX document with `data`.** The template holds fields such as `{{ candidateName }}`. The `data` object supplies one string for each. See [Document templates](https://signatureapi.com/docs/api/resources/documents/templates).
- **Two recipients.** The hiring manager is an `approver`, the candidate is a `signer`. Approvers get no signature place.
- **Places by fixed position.** The sample template has no `[[placeholders]]`, so the signature and the signing date use `fixed_positions`. With a `[[candidate_signature]]` placeholder in your own template you can drop them. See [Use placeholders](https://signatureapi.com/docs/api/guides/how-to/use-placeholders).
- **Metadata and topics.** `metadata.ats_candidate_id` carries your ATS id so a webhook handler can find the candidate. `topics` group offer letters for filtering.

## Routing

The envelope uses `sequential` routing, so the order of the `recipients` array is the order of the steps. The hiring manager approves first. The candidate receives the letter only after that. 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 when the approver approves and again when the candidate signs. Read `recipient_key` and `envelope_metadata.ats_candidate_id` to update the right candidate.
- [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events): every recipient has finished. Mark the offer as accepted.
- [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events): the signed letter and audit log are ready to download and attach to the candidate record.

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 valid for an employment offer depends on your jurisdiction and your employer policies, so have counsel review your template and process. Keep personal data such as salary out of `metadata`, which appears in webhook payloads; send it only in the document `data`.

### Example: Default

Offer Letter - Jane Doe.

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

{
  "title": "Offer Letter - Jane Doe",
  "message": "Please review your offer letter and sign it to accept.",
  "routing": "sequential",
  "metadata": {
    "ats_candidate_id": "cand_1042",
    "source": "ats"
  },
  "topics": [
    "hr",
    "offer_letters"
  ],
  "documents": [
    {
      "key": "offer_letter",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/offer-letter-template.docx",
      "format": "docx",
      "data": {
        "date": "November 17, 2026",
        "candidateName": "Jane Doe",
        "jobTitle": "Product Designer",
        "startDate": "January 11, 2027",
        "salary": "$95,000"
      },
      "fixed_positions": [
        {
          "place_key": "candidate_signature",
          "page": 1,
          "top": 300,
          "left": 72
        },
        {
          "place_key": "signed_on",
          "page": 1,
          "top": 330,
          "left": 72
        }
      ],
      "places": [
        {
          "key": "candidate_signature",
          "type": "signature",
          "recipient_key": "candidate"
        },
        {
          "key": "signed_on",
          "type": "recipient_completed_date",
          "recipient_key": "candidate"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "approver",
      "key": "hiring_manager",
      "name": "Alex Chen",
      "email": "alex.chen@example.com"
    },
    {
      "type": "signer",
      "key": "candidate",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Offer Letter - Jane Doe",
  "label": null,
  "message": "Please review your offer letter and sign it to accept.",
  "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": [
      "offer_letter"
    ]
  },
  "metadata": {
    "ats_candidate_id": "cand_1042",
    "source": "ats"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {},
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "offer_letter",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/offer-letter-template.docx",
      "format": "docx",
      "data": {
        "date": "November 17, 2026",
        "candidateName": "Jane Doe",
        "jobTitle": "Product Designer",
        "startDate": "January 11, 2027",
        "salary": "$95,000"
      },
      "fixed_positions": [
        {
          "page": 1,
          "top": 300,
          "left": 72,
          "place_key": "candidate_signature"
        },
        {
          "page": 1,
          "top": 330,
          "left": 72,
          "place_key": "signed_on"
        }
      ],
      "places": [
        {
          "key": "candidate_signature",
          "type": "signature",
          "recipient_key": "candidate",
          "height": 60
        },
        {
          "key": "signed_on",
          "type": "recipient_completed_date",
          "recipient_key": "candidate",
          "date_format": "D MMM YYYY",
          "font_size": 12
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "approver",
      "key": "hiring_manager",
      "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": "candidate",
      "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": [
    "hr",
    "offer_letters"
  ],
  "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.
