Skip to content

Industries

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.

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 and 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.
  • 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.
  • 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.

Webhooks to listen for

  • recipient.completed: fires when the candidate signs. Read envelope_metadata.record_id to mark that candidate as signed in your list.
  • recipient.rejected: the candidate declined. Flag the row for follow-up; the envelope stays open until you replace the recipient or cancel it.
  • deliverable.generated: 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.

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

Default
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)"
    }
  ]
}
{
  "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
}

Errors every call can return are in Errors and Authentication.