Industries
Collect Patient Consent and Intake Forms
Send a consent form that a patient reaches by email link and unlocks with an emailed code, with a required consent checkbox and no health data in the request.
A consent form is often sent by email, and an email link alone does not prove who opens it. Ask the patient for a second step, an emailed code, before the form opens. Keep the request itself free of health data and join on an opaque reference instead.
Envelope shape
- Two authentication methods. The signer’s
ceremony.authenticationlistsemail_linkand thenemail_code. The patient gets the link in one email and must enter a code sent in another. See Multiple authentication methods. - No health data in the request.
metadata.visit_refis an opaque reference. Do not put diagnoses, record numbers or free text about the patient inmetadata,titleormessage. Keep those in your own system and join on the reference. - A required checkbox. The
consent_givenplace is acheckboxwithrequirement: "required".capture_asstores the answer in the envelope’scaptures. See Checkbox places. - A signature place. The patient signs. The sample PDF is a stand-in for your own consent form.
Routing
There is one recipient, so routing does not change the flow. The envelope takes the default, sequential, which is the routing the checkbox place requires. See Recipient routing.
Webhooks to listen for
recipient.completed: the patient consented and signed. Useenvelope_metadata.visit_refto find the visit.recipient.rejected: the patient declined. Notify the clinic; do not treat the visit as consented.deliverable.generated: the signed form and audit log are ready. Download them into your records system.
Set up the endpoint as shown in Set up webhooks.
Compliance notes
This is general information, not legal advice. If you handle protected health information, read HIPAA at SignatureAPI for the authentication, deliverable download and Business Associate Agreement (BAA) details. Whether an electronic signature is enough for a given consent form depends on your jurisdiction and your policies, so have counsel review the form and the process.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Treatment Consent (sample)",
"message": "Please review and sign the consent form. You will also need the code we email you separately.",
"metadata": {
"visit_ref": "visit_5521"
},
"topics": [
"healthcare",
"consent"
],
"documents": [
{
"key": "consent_form",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "consent_given",
"page": 1,
"top": 140,
"left": 210
},
{
"place_key": "patient_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "consent_given",
"type": "checkbox",
"recipient_key": "patient",
"requirement": "required",
"capture_as": "consent_given"
},
{
"key": "patient_signature",
"type": "signature",
"recipient_key": "patient"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "patient",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"ceremony": {
"authentication": [
{
"type": "email_link"
},
{
"type": "email_code"
}
]
}
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Treatment Consent (sample)",
"message": "Please review and sign the consent form. You will also need the code we email you separately.",
"metadata": {
"visit_ref": "visit_5521"
},
"topics": [
"healthcare",
"consent"
],
"documents": [
{
"key": "consent_form",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "consent_given",
"page": 1,
"top": 140,
"left": 210
},
{
"place_key": "patient_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "consent_given",
"type": "checkbox",
"recipient_key": "patient",
"requirement": "required",
"capture_as": "consent_given"
},
{
"key": "patient_signature",
"type": "signature",
"recipient_key": "patient"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "patient",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"ceremony": {
"authentication": [
{
"type": "email_link"
},
{
"type": "email_code"
}
]
}
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Treatment Consent (sample)",
"message": "Please review and sign the consent form. You will also need the code we email you separately.",
"metadata": {
"visit_ref": "visit_5521"
},
"topics": [
"healthcare",
"consent"
],
"documents": [
{
"key": "consent_form",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "consent_given",
"page": 1,
"top": 140,
"left": 210
},
{
"place_key": "patient_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "consent_given",
"type": "checkbox",
"recipient_key": "patient",
"requirement": "required",
"capture_as": "consent_given"
},
{
"key": "patient_signature",
"type": "signature",
"recipient_key": "patient"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "patient",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"ceremony": {
"authentication": [
{
"type": "email_link"
},
{
"type": "email_code"
}
]
}
}
]
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Treatment Consent (sample)",
"label": null,
"message": "Please review and sign the consent form. You will also need the code we email you separately.",
"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": [
"consent_form"
]
},
"metadata": {
"visit_ref": "visit_5521"
},
"sender": {
"name": "Acme Corp Legal",
"email": "legal@acme.example",
"organization": "Acme Corp"
},
"captures": {
"consent_given": false
},
"documents": [
{
"id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "consent_form",
"title": null,
"page_count": 1,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"page": 1,
"top": 140,
"left": 210,
"place_key": "consent_given"
},
{
"page": 1,
"top": 172,
"left": 210,
"place_key": "patient_signature"
}
],
"places": [
{
"key": "consent_given",
"type": "checkbox",
"recipient_key": "patient",
"height": 20,
"symbol": "check",
"capture_as": "consent_given",
"requirement": "required"
},
{
"key": "patient_signature",
"type": "signature",
"recipient_key": "patient",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "patient",
"email": "jane.doe@example.com",
"name": "Jane Doe",
"ceremony": {
"authentication": [
{
"type": "email_link",
"subject_override": null,
"message_override": null
},
{
"type": "email_code"
}
],
"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": [
"healthcare",
"consent"
],
"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.