---
title: "Onboard Staffing Workers in Bulk"
description: "Send one placement agreement per row of a CSV, collect each worker's signature, and countersign for the agency automatically with an automatic signer."
canonical: "https://signatureapi.com/docs/use-cases/staffing-onboarding"
source: "https://signatureapi.com/docs/use-cases/staffing-onboarding.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:55Z"
---

# Onboard Staffing Workers in Bulk

Send one placement agreement per row of a CSV, collect each worker's signature, and countersign for the agency automatically with an automatic signer.

_Last verified against API version 1.18.0._

A staffing agency onboards dozens of workers a week, and the agency countersigns every agreement. Waiting for a person to countersign each one is the bottleneck. Loop over your candidate list, create one envelope per row, and let an automatic signer apply the agency signature as soon as the envelope is created.

## Envelope shape

- **One envelope per candidate.** Call `POST /v1/envelopes` once per CSV row. `metadata.record_id` holds the row id and `metadata.batch_id` names the wave, so you can reconcile envelopes with your list. `topics` tag the batch. See [Metadata](https://signatureapi.com/docs/api/resources/envelopes/metadata) and [Topics](https://signatureapi.com/docs/api/resources/envelopes/topics).
- **A signer and an automatic signer.** The candidate is a `signer`. The agency is an `automatic_signer` with a `signature` image from `POST /v1/uploads` and a `mandate` that records why you may sign on its behalf. No email is sent and no ceremony is created. See [Automatic signer](https://signatureapi.com/docs/api/resources/recipients/automatic-signer).
- **Two signature places.** Each place points at its recipient with `recipient_key`. The sample PDF has no placeholders, so both use `fixed_positions`. See [Place positioning](https://signatureapi.com/docs/api/resources/places/positioning).
- **Keep the message free of phone-like text.** The `title` and `message` are shown to recipients and are checked for URLs and phone numbers. A run of seven or more digits counts as a phone number, so keep dates such as `2026-11-02` out of them and put them in `metadata` instead.

## Routing

The envelope uses `sequential` routing. The candidate is first in `recipients`, so the candidate signs first. The automatic signer applies its signature at creation, so the agency never holds up the envelope. See [Recipient routing](https://signatureapi.com/docs/api/resources/envelopes/routing).

## Webhooks to listen for

- [`recipient.completed`](https://signatureapi.com/docs/api/resources/events/recipient-events): fires when the candidate signs. Read `envelope_metadata.record_id` to mark that candidate as signed in your list.
- [`recipient.rejected`](https://signatureapi.com/docs/api/resources/events/recipient-events): the candidate declined. Flag the row for follow-up; the envelope stays open until you replace the recipient or cancel it.
- [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events): the signed agreement and audit log are ready. Download them and attach them to the worker 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. The automatic signer applies a signature without the agency's representative interacting with the document, and its legal weight differs by jurisdiction, as the [automatic signer](https://signatureapi.com/docs/api/resources/recipients/automatic-signer) page explains. Have counsel confirm that your mandate and process fit the places where you place workers. Keep personal data out of `metadata`, which appears in webhook payloads.

### Example: Default

Placement Agreement - Jane Doe.

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

{
  "title": "Placement Agreement - Jane Doe",
  "message": "Please sign your placement agreement for the Warehouse Associate role.",
  "routing": "sequential",
  "metadata": {
    "record_id": "cand_2001",
    "batch_id": "2026_11_wave_1"
  },
  "topics": [
    "staffing",
    "onboarding"
  ],
  "documents": [
    {
      "key": "placement_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "candidate_signature",
          "page": 1,
          "top": 172,
          "left": 210
        },
        {
          "place_key": "agency_countersignature",
          "page": 1,
          "top": 186,
          "left": 220
        }
      ],
      "places": [
        {
          "key": "candidate_signature",
          "type": "signature",
          "recipient_key": "candidate"
        },
        {
          "key": "agency_countersignature",
          "type": "signature",
          "recipient_key": "agency"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "candidate",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    },
    {
      "type": "automatic_signer",
      "key": "agency",
      "name": "Acme Corp Authorized Signatory",
      "signature": {
        "type": "drawn",
        "url": "https://api.signatureapi.com/v1/uploads/upl_2bC6tF9gHk3LmQ8rSx5Vy7"
      },
      "mandate": "Authorized by Acme Corp board resolution 2026-04 (synthetic example)"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Placement Agreement - Jane Doe",
  "label": null,
  "message": "Please sign your placement agreement for the Warehouse Associate role.",
  "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": [
      "placement_agreement"
    ]
  },
  "metadata": {
    "record_id": "cand_2001",
    "batch_id": "2026_11_wave_1"
  },
  "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": "placement_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": "candidate_signature"
        },
        {
          "page": 1,
          "top": 186,
          "left": 220,
          "place_key": "agency_countersignature"
        }
      ],
      "places": [
        {
          "key": "candidate_signature",
          "type": "signature",
          "recipient_key": "candidate",
          "height": 60
        },
        {
          "key": "agency_countersignature",
          "type": "signature",
          "recipient_key": "agency",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
      "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
    },
    {
      "id": "re_OcsAUqEe6a6eEqUAscOC2u",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "automatic_signer",
      "key": "agency",
      "name": "Acme Corp Authorized Signatory",
      "signature": {
        "type": "drawn",
        "url": "https://api.signatureapi.com/v1/uploads/upl_2bC6tF9gHk3LmQ8rSx5Vy7"
      },
      "initials": null,
      "mandate": "Authorized by Acme Corp board resolution 2026-04 (synthetic example)",
      "status": "awaiting",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "staffing",
    "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,
  "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.
