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/envelopesonce per CSV row.metadata.record_idholds the row id andmetadata.batch_idnames the wave, so you can reconcile envelopes with your list.topicstag the batch. See Metadata and Topics. - A signer and an automatic signer. The candidate is a
signer. The agency is anautomatic_signerwith asignatureimage fromPOST /v1/uploadsand amandatethat 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 usefixed_positions. See Place positioning. - Keep the message free of phone-like text. The
titleandmessageare 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 as2026-11-02out of them and put them inmetadatainstead.
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. Readenvelope_metadata.record_idto 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.
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)"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"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)"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"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
}{
"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 every call can return are in Errors and Authentication.