HR and hiring
Send Onboarding Packets From BambooHR
Send a new hire an onboarding packet when BambooHR creates the employee, using a BambooHR webhook and an HTTP step in your automation tool.
BambooHR sends a webhook when an employee record is created. Its payload is fixed, so you can’t point the webhook straight at the SignatureAPI REST API. Send it to an inbound webhook in an automation tool, then let that tool’s HTTP step create the envelope. No SignatureAPI app is needed.
The packet is one envelope with two documents and one signer, the new hire. See HR offer letters for the offer stage that comes before it.
Before you start
- A SignatureAPI test API key (it starts with
key_test_). - Both documents at URLs on a supported host, or uploaded to SignatureAPI first. The example uses a sample PDF for both.
- An automation tool with an inbound webhook and an HTTP step: Make, Zapier or n8n.
Receive the new hire from BambooHR
Copy the tool's webhook URL
Create an inbound webhook in your automation tool and copy its HTTPS URL. BambooHR accepts only HTTPS URLs.
Create the BambooHR webhook
BambooHR has two kinds. Global webhooks are configured by administrators in the BambooHR settings and watch a fixed list of standard fields. Permissioned webhooks are created through the BambooHR API and can watch any field the API user can access, including Hire Date and Status. Choose JSON as the format. See BambooHR webhooks.
Read the payload
BambooHR sends an HTTP POST with a list named employees. Each entry has the BambooHR employee id, the changedFields that triggered it and the configured field data in fields. One request can batch several employees, so loop over the list. BambooHR also documents an employee.created event whose data holds only companyId and employeeId; see Employee Created.
Look up the name and email if needed
If the payload lacks them, call GET /api/v1/employees/{id}?fields=firstName,lastName,workEmail on your BambooHR domain. Without the fields parameter the response holds only the id. See Get employee.
BambooHR signs deliveries with the X-BambooHR-Signature and X-BambooHR-Timestamp headers, an HMAC-SHA256 over the raw body, the timestamp and your private key. Verify them if your tool lets you.
Send the packet
Add an HTTP step after the webhook and map the employee’s name and email into the body.
HTTP request step
Settings for the "Onboarding packet" 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": "Onboarding Packet - Jane Doe",
"message": "Welcome aboard. Please review and sign your onboarding documents.",
"metadata": {
"source": "bamboohr",
"employee_id": "1042"
},
"topics": [
"hr",
"onboarding"
],
"documents": [
{
"key": "employment_agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "agreement_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "agreement_signature",
"type": "signature",
"recipient_key": "employee"
}
]
},
{
"key": "handbook_acknowledgment",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "handbook_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "handbook_signature",
"type": "signature",
"recipient_key": "employee"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "employee",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}data.envelope_metadata.employee_id comes back in every webhook event for this envelope, so map the BambooHR employee id there. The onboarding topic lets a SignatureAPI webhook endpoint receive only these envelopes. Both documents share one employee recipient, so the new hire signs the whole packet in one session.
Get the result back
Add a webhook endpoint in the Dashboard, in test mode, pointing at a second inbound webhook in your tool. Subscribe to deliverable.generated, which fires when the signed PDF is ready, and add the onboarding 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 act. The event body gives the envelope in data.envelope_id.
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.employee_id names the employee, and deliverable.url downloads the signed PDF. That link expires after an hour, so download the file in the same run. If your account uses authenticated deliverable URLs, send your API key with the download.
BambooHR can store the file on the employee record: POST https://{companyDomain}.bamboohr.com/api/v1/employees/{id}/files takes a multipart/form-data body with file, fileName and category (the ID of the employee file section), plus an optional share of yes or no. See Upload Employee File.
Related
- Create an envelope: every field of the request body.
- HR offer letters.
- Set up webhooks.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Onboarding Packet - Jane Doe",
"message": "Welcome aboard. Please review and sign your onboarding documents.",
"metadata": {
"source": "bamboohr",
"employee_id": "1042"
},
"topics": [
"hr",
"onboarding"
],
"documents": [
{
"key": "employment_agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "agreement_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "agreement_signature",
"type": "signature",
"recipient_key": "employee"
}
]
},
{
"key": "handbook_acknowledgment",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "handbook_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "handbook_signature",
"type": "signature",
"recipient_key": "employee"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "employee",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Onboarding Packet - Jane Doe",
"message": "Welcome aboard. Please review and sign your onboarding documents.",
"metadata": {
"source": "bamboohr",
"employee_id": "1042"
},
"topics": [
"hr",
"onboarding"
],
"documents": [
{
"key": "employment_agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "agreement_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "agreement_signature",
"type": "signature",
"recipient_key": "employee"
}
]
},
{
"key": "handbook_acknowledgment",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "handbook_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "handbook_signature",
"type": "signature",
"recipient_key": "employee"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "employee",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Onboarding Packet - Jane Doe",
"message": "Welcome aboard. Please review and sign your onboarding documents.",
"metadata": {
"source": "bamboohr",
"employee_id": "1042"
},
"topics": [
"hr",
"onboarding"
],
"documents": [
{
"key": "employment_agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "agreement_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "agreement_signature",
"type": "signature",
"recipient_key": "employee"
}
]
},
{
"key": "handbook_acknowledgment",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "handbook_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "handbook_signature",
"type": "signature",
"recipient_key": "employee"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "employee",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Onboarding Packet - Jane Doe",
"label": null,
"message": "Welcome aboard. Please review and sign your onboarding documents.",
"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": [
"employment_agreement",
"handbook_acknowledgment"
]
},
"metadata": {
"source": "bamboohr",
"employee_id": "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": "employment_agreement",
"title": null,
"page_count": 1,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"page": 1,
"top": 172,
"left": 210,
"place_key": "agreement_signature"
}
],
"places": [
{
"key": "agreement_signature",
"type": "signature",
"recipient_key": "employee",
"height": 60
}
]
},
{
"id": "doc_OcsAUqEe6a6eEqUAscOC2u",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "handbook_acknowledgment",
"title": null,
"page_count": 1,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"page": 1,
"top": 172,
"left": 210,
"place_key": "handbook_signature"
}
],
"places": [
{
"key": "handbook_signature",
"type": "signature",
"recipient_key": "employee",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_49r1R2jpPDz8hSpP75ZkPp",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "employee",
"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",
"onboarding"
],
"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.