---
title: "Send Onboarding Documents From Workday"
description: "Send onboarding documents for signing when your Workday integration passes a new worker's details to an HTTP endpoint that creates the envelope."
canonical: "https://signatureapi.com/docs/integrations/workday"
source: "https://signatureapi.com/docs/integrations/workday.md"
last_verified_api_version: "1.18.0"
---

# Send Onboarding Documents From Workday

Send onboarding documents for signing when your Workday integration passes a new worker's details to an HTTP endpoint that creates the envelope.

_Last verified against API version 1.18.0._

This page describes the pattern, not Workday menus. Workday outbound connectors send data from Workday to an external system and output it as XML, according to [Workday connectors](https://doc.workday.com/workday-education/en-us/course-manuals/creating-and-securing-integrations/workday-connectors.html). Your Workday integration, or the middleware your team uses with it, sends the new worker's details to an HTTP endpoint you control. That endpoint makes one request to SignatureAPI. No SignatureAPI app is needed.

## Before you start

- A SignatureAPI [test API key](https://signatureapi.com/docs/api/test-mode) (it starts with `key_test_`).
- The 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.
- An endpoint that receives the worker's details. This can be an inbound webhook in [Make](https://signatureapi.com/docs/integrations/make), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) or [n8n](https://signatureapi.com/docs/integrations/n8n), or a service you run. Ask your Workday administrator how your integration delivers data to it.

## Send the envelope

Convert the worker's details to JSON if your integration sends XML, then make this request from the endpoint or from the HTTP step of your tool. Map the worker's name and email into `recipients[0]` and the worker id into `metadata.worker_id`.

HTTP request step settings for the "Onboarding documents" 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 Documents - Jane Doe",
     "message": "Welcome aboard. Please review and sign your onboarding documents.",
     "metadata": {
       "source": "workday",
       "worker_id": "21001"
     },
     "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"
           }
         ]
       }
     ],
     "recipients": [
       {
         "type": "signer",
         "key": "employee",
         "name": "Jane Doe",
         "email": "jane.doe@example.com"
       }
     ]
   }
   ```

`data.envelope_metadata.worker_id` comes back in every webhook event for this envelope. The `onboarding` topic lets a webhook endpoint receive only these envelopes.

## 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, subscribed to [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events#deliverablegenerated), which fires when the signed PDF is ready, with 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 the endpoint URL can call it, so read the envelope with your key before you act.

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.

Check that `deliverable.status` is `generated`. `metadata.worker_id` names the worker, and `deliverable.url` downloads the signed PDF. That link expires after an hour, so download the file in the same run and store it where your team keeps worker documents. If your account uses [authenticated deliverable URLs](https://signatureapi.com/docs/api/resources/deliverables/object#url), send your API key with the download.

## Related

- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create).
- [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 documents

Onboarding documents for one new worker.

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

{
  "title": "Onboarding Documents - Jane Doe",
  "message": "Welcome aboard. Please review and sign your onboarding documents.",
  "metadata": {
    "source": "workday",
    "worker_id": "21001"
  },
  "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"
        }
      ]
    }
  ],
  "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 Documents - 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"
    ]
  },
  "metadata": {
    "source": "workday",
    "worker_id": "21001"
  },
  "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
        }
      ]
    }
  ],
  "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.
