---
title: "Send Onboarding Packets From BambooHR"
description: "Send a new hire an onboarding packet when BambooHR creates the employee, using a BambooHR webhook and an HTTP step in your automation tool."
canonical: "https://signatureapi.com/docs/integrations/bamboohr"
source: "https://signatureapi.com/docs/integrations/bamboohr.md"
last_verified_api_version: "1.18.0"
---

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

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/use-cases/hr-offer-letters) for the offer stage that comes before it.

## Before you start

- A SignatureAPI [test API key](https://signatureapi.com/docs/api/test-mode) (it starts with `key_test_`).
- Both documents at URLs on a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store), or [uploaded to SignatureAPI](https://signatureapi.com/docs/api/resources/uploads/create) first. The example uses a sample PDF for both.
- An automation tool with an inbound webhook and an HTTP step: [Make](https://signatureapi.com/docs/integrations/make), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) or [n8n](https://signatureapi.com/docs/integrations/n8n).

## Receive the new hire from BambooHR

1. **Copy the tool's webhook URL**

   Create an inbound webhook in your automation tool and copy its HTTPS URL. BambooHR accepts only HTTPS URLs.

2. **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](https://documentation.bamboohr.com/docs/webhooks).

3. **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](https://documentation.bamboohr.com/reference/employee-created-webhook).

4. **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](https://documentation.bamboohr.com/reference/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:

1. **Method**: POST
2. **URL**: `https://api.signatureapi.com/v1/envelopes`
3. **Header**: `X-API-Key: YOUR_API_KEY`

   Store the key in your tool's secret or credential storage when it has one.
4. **Header**: `Content-Type: application/json`
5. **Body (raw JSON)**:

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

`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](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks) in the Dashboard, in test mode, pointing at a second inbound webhook in your tool. Subscribe to [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events#deliverablegenerated), which fires when the signed PDF is ready, and add the `onboarding` topic. The [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopecompleted) 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:

1. **Method**: GET
2. **URL**: `https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`
3. **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](https://signatureapi.com/docs/api/resources/deliverables/object#url), 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](https://documentation.bamboohr.com/reference/upload-employee-file).

## Related

- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create): every field of the request body.
- [HR offer letters](https://signatureapi.com/docs/use-cases/hr-offer-letters).
- [Set up webhooks](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks).

### Example: Onboarding packet

Two documents for one new hire.

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

Response 201 Created:

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

Response 422 Unprocessable Content:

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