Industries
Sign Service Contracts In Store or In App
Create a service contract, then embed its ceremony on a store tablet or in your app, with an emailed code that confirms the customer owns the email address.
A customer signs a service contract at the counter. The clerk has a tablet, and the customer has an email address but no login. You want signing to happen right there, with a check that the customer owns the email. A ceremony with email_code authentication returns a URL you can embed, and SignatureAPI emails the customer a code to enter first.
Envelope shape
- One PDF with three places. A
dropdownfor the plan, aninitialsplace for the fee schedule and asignature, all for thecustomer.capture_as: planstores the selected value incaptures. See Dropdown and Captures. delivery_type: "none". SignatureAPI does not email the signed documents to the customer. Your store system prints or stores them. See Signer.- Order metadata.
order_idandstore_idlet a handler match events to the sale. See Metadata.
Routing
There is one signer, so the envelope uses the default sequential routing. The dropdown is a form place, and dropdowns are only available with sequential signing.
The envelope does not set a ceremony. Once it is in_progress, call POST /v1/recipients/{recipient_id}/ceremonies with authentication: [{ "type": "email_code" }]. Because email_code comes first, the response includes the ceremony url and your app delivers it. Set embeddable_in to the store app origin and url_variant to short, which is easy to show as a QR code. See Email code authentication, the embedded signing guide and, for native apps, Embed in a mobile app.
Webhooks to listen for
envelope.started: the envelope isin_progress, so you can create the ceremony.recipient.completed: the customer signed. Readenvelope_metadata.order_idto activate the order.deliverable.generated: the signed contract and audit log are ready to print or store.
Compliance notes
This is general information, not legal advice. Consumer contract and signature rules for telecom services vary by jurisdiction and regulator, so have counsel review your contract and process. The emailed code shows that the customer can read that mailbox. It does not verify who they are. The ceremony URL is a bearer credential: anyone who has it can open the ceremony, so do not log it. Keep personal data out of metadata.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Contract (sample)",
"metadata": {
"order_id": "ord_telco_1",
"store_id": "store_12"
},
"topics": [
"telecom",
"service_contracts"
],
"documents": [
{
"key": "service_contract",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "plan",
"page": 1,
"top": 130,
"left": 210
},
{
"place_key": "fee_initials",
"page": 1,
"top": 250,
"left": 72
},
{
"place_key": "customer_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "plan",
"type": "dropdown",
"recipient_key": "customer",
"prompt": "Plan",
"options": [
{
"label": "Basic",
"value": "basic"
},
{
"label": "Unlimited",
"value": "unlimited"
}
],
"width": 120,
"capture_as": "plan"
},
{
"key": "fee_initials",
"type": "initials",
"recipient_key": "customer",
"height": 30
},
{
"key": "customer_signature",
"type": "signature",
"recipient_key": "customer"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "customer",
"name": "John Smith",
"email": "john.smith@example.com",
"delivery_type": "none"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Service Contract (sample)",
"metadata": {
"order_id": "ord_telco_1",
"store_id": "store_12"
},
"topics": [
"telecom",
"service_contracts"
],
"documents": [
{
"key": "service_contract",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "plan",
"page": 1,
"top": 130,
"left": 210
},
{
"place_key": "fee_initials",
"page": 1,
"top": 250,
"left": 72
},
{
"place_key": "customer_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "plan",
"type": "dropdown",
"recipient_key": "customer",
"prompt": "Plan",
"options": [
{
"label": "Basic",
"value": "basic"
},
{
"label": "Unlimited",
"value": "unlimited"
}
],
"width": 120,
"capture_as": "plan"
},
{
"key": "fee_initials",
"type": "initials",
"recipient_key": "customer",
"height": 30
},
{
"key": "customer_signature",
"type": "signature",
"recipient_key": "customer"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "customer",
"name": "John Smith",
"email": "john.smith@example.com",
"delivery_type": "none"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Service Contract (sample)",
"metadata": {
"order_id": "ord_telco_1",
"store_id": "store_12"
},
"topics": [
"telecom",
"service_contracts"
],
"documents": [
{
"key": "service_contract",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "plan",
"page": 1,
"top": 130,
"left": 210
},
{
"place_key": "fee_initials",
"page": 1,
"top": 250,
"left": 72
},
{
"place_key": "customer_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "plan",
"type": "dropdown",
"recipient_key": "customer",
"prompt": "Plan",
"options": [
{
"label": "Basic",
"value": "basic"
},
{
"label": "Unlimited",
"value": "unlimited"
}
],
"width": 120,
"capture_as": "plan"
},
{
"key": "fee_initials",
"type": "initials",
"recipient_key": "customer",
"height": 30
},
{
"key": "customer_signature",
"type": "signature",
"recipient_key": "customer"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "customer",
"name": "John Smith",
"email": "john.smith@example.com",
"delivery_type": "none"
}
]
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Service Contract (sample)",
"label": null,
"message": null,
"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": [
"service_contract"
]
},
"metadata": {
"order_id": "ord_telco_1",
"store_id": "store_12"
},
"sender": {
"name": "Acme Corp Legal",
"email": "legal@acme.example",
"organization": "Acme Corp"
},
"captures": {
"plan": null
},
"documents": [
{
"id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "service_contract",
"title": null,
"page_count": 1,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"page": 1,
"top": 130,
"left": 210,
"place_key": "plan"
},
{
"page": 1,
"top": 250,
"left": 72,
"place_key": "fee_initials"
},
{
"page": 1,
"top": 172,
"left": 210,
"place_key": "customer_signature"
}
],
"places": [
{
"key": "plan",
"type": "dropdown",
"recipient_key": "customer",
"capture_as": "plan",
"hint": null,
"prompt": "Plan",
"requirement": "required",
"font_size": 12,
"width": 120,
"default": null,
"behavior": "auto",
"options": [
{
"label": "Basic",
"value": "basic"
},
{
"label": "Unlimited",
"value": "unlimited"
}
]
},
{
"key": "fee_initials",
"type": "initials",
"recipient_key": "customer",
"height": 30
},
{
"key": "customer_signature",
"type": "signature",
"recipient_key": "customer",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "customer",
"email": "john.smith@example.com",
"name": "John Smith",
"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": "none",
"signature_options": [
"typed",
"drawn"
],
"status": "pending",
"status_updated_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
}
],
"topics": [
"telecom",
"service_contracts"
],
"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.