HR and hiring
Send Offer Letters From Greenhouse and Lever
Send a DOCX offer letter for signing when Greenhouse or Lever fires a webhook, using an automation tool or your own endpoint and an HTTP request.
Greenhouse and Lever both send webhooks when a hiring step happens. Their payloads are fixed, so receive the webhook in an automation tool’s inbound webhook or in your own endpoint, then make one HTTP request to create the envelope. No SignatureAPI app is needed. For the envelope design, see HR offer letters.
Before you start
- A SignatureAPI test API key (it starts with
key_test_). - A DOCX offer letter with
{{ field }}merge fields, at a URL on a supported host or uploaded to SignatureAPI first. See Document templates. - An automation tool with an inbound webhook and an HTTP step (Make, Zapier or n8n), or an HTTPS endpoint you run.
Receive the offer from your ATS
Greenhouse. A webhook has a name, an HTTPS endpoint URL and a secret key. Greenhouse pings the URL when you save it, and creates the webhook disabled if the ping fails. Subscribe to the offer events: offer_approved fires when an offer that required approval receives it, and offer_created fires for a new offer or version. The JSON body has payload.offer with application_id, job_id, start_date and custom_fields. Salary appears only if your organization has a currency custom field on offers. Each delivery has a Signature header, an HMAC-SHA256 over the raw body with your secret key. See Greenhouse webhooks.
Lever. A Super Admin enables events and sets a URL for each on the Webhooks tab of the integration settings. Lever has no offer event. The closest are candidateStageChange, which fires when a candidate moves to a new stage, and candidateHired. Pick the stage that means the offer is approved. The POST body has triggeredAt, event, data, signature and token, and the URL must be HTTPS. Lever also lists offers in its API, so you can look the offer up from the candidate. See Lever developer documentation.
Send the envelope
Add an HTTP step after the webhook and map the candidate fields into the body: the candidate’s name and email into recipients[0], and the offer values into documents[0].data.
HTTP request step
Settings for the "Offer letter" request.
| Setting | Value |
|---|---|
| Method | POST |
| URL | https:// |
| Header | X-API-Key: YOUR_API_KEY Store the key in your tool's secret or credential storage when it has one. |
| Header | Content- |
| Body (raw JSON) | The JSON below. |
{
"title": "Offer Letter - Jane Doe",
"message": "Please review your offer letter and sign it to accept.",
"metadata": {
"source": "ats",
"application_id": "app_1042"
},
"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": "signer",
"key": "candidate",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}Each key in data fills the matching {{ field }} in the template. Keep salary in data, never in metadata: metadata appears in every webhook payload. metadata.application_id carries your ATS id so you can find the candidate later, and the offer_letters topic lets an endpoint receive only offer envelopes.
Get the result back
Add a webhook endpoint in the Dashboard, in test mode, pointing at a second inbound webhook or at your endpoint. Subscribe to deliverable.generated, which fires when the signed PDF is ready, and add the offer_letters topic. The envelope.completed event comes earlier, while the PDF may still be generating, so use it only to update a status.
Anyone who knows that URL can call it, so read the envelope with your key before you update the candidate.
HTTP request step
Settings for the "Completed envelope" request.
| Setting | Value |
|---|---|
| Method | GET |
| URL | https:// |
| Header | X-API-Key: YOUR_API_KEY Store the key in your tool's secret or credential storage when it has one. |
Act on the response: deliverable.status is generated, metadata.application_id names the application, and deliverable.url downloads the signed letter. That link expires after an hour, so download it in the same run and attach it to the candidate in your ATS. If your account uses authenticated deliverable URLs, send your API key with the download.
Related
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.",
"metadata": {
"source": "ats",
"application_id": "app_1042"
},
"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": "signer",
"key": "candidate",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Offer Letter - Jane Doe",
"message": "Please review your offer letter and sign it to accept.",
"metadata": {
"source": "ats",
"application_id": "app_1042"
},
"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": "signer",
"key": "candidate",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Offer Letter - Jane Doe",
"message": "Please review your offer letter and sign it to accept.",
"metadata": {
"source": "ats",
"application_id": "app_1042"
},
"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": "signer",
"key": "candidate",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}
}{
"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_6FF89lKNyTNamOJCJd1tLL",
"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": {
"source": "ats",
"application_id": "app_1042"
},
"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_49r1R2jpPDz8hSpP75ZkPp",
"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": "pending",
"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
}{
"type": "https://signatureapi.com/docs/v1/errors/validation-error",
"title": "Validation Error",
"status": 422,
"errors": [
"recipients[0].email must be a valid email address."
]
}Errors every call can return are in Errors and Authentication.