Signers, roles and order

Who a document goes to, what each of them does, and in what order. Said once, when it is sent.

The request

Order is a property of the document, so it is set when the document is prepared: sequential on POST /v1/documents, false when absent. The people are set when it is sent, on POST /v1/documents/{id}/send, one to fifty of them.

POST /v1/documents
{ "template_code": "equipment-rental",
  "values": { "renter": "Dana Reyes", "boat": "Tandem kayak 4" },
  "sequential": true }

POST /v1/documents/{id}/send
{ "signers": [
    { "full_name": "Dana Reyes", "email": "dana@example.signsealer.com",
      "phone": "+16155550142", "role": "signer", "sign_order": 1 },
    { "full_name": "Lee Park", "email": "lee@example.signsealer.com",
      "role": "witness", "sign_order": 2 },
    { "full_name": "Priya Shah", "email": "priya@example.signsealer.com",
      "role": "approver", "sign_order": 3 },
    { "full_name": "Front desk", "email": "desk@example.signsealer.com", "role": "cc" }
  ] }

Everyone but a cc needs an email, a phone, or both; given both, the same link goes by each. The answer is one link per person, once, and only the hash of each is kept. A document takes its signers once: sending one that has already gone out is refused with 422.

Roles

Every role that signs is asked every question on the template, each answering for themselves (Questions and fields), and every one of them has to sign before the document completes.

Order

With sequential false, which is the default, everybody signs when they like and sign_order only orders the lists.

With sequential true, a link takes a signature only once everybody with a lower sign_order has signed, copied recipients aside. People with the same sign_order are one step and sign in any order between them; the step after waits for all of them. Opened too soon, the page says It is not your turn yet. This document is signed in order, and somebody before you has not signed.; GET /v1/sign/{token} answers is_my_turn: false; and POST /v1/sign/{token} is refused with 422, an earlier signer has not signed yet.

One address, or one number, can be on a document once at each step. The same person twice at the same sign_order is refused with 409; at two steps, they are two signers with a link each.

Who it is waiting on

waiting_on on GET /v1/documents names everybody who signs and has not, in step order, separated by commas, and is null once nobody is left. It is who has not signed, not whose turn it is: in a sequential document it names the later steps too. The signing link answers the same list, leaving out the person reading it, and the page shows it to them under the Sign button (After you, this still needs …) and once they have signed. For each person's step and state, read GET /v1/documents/{id}/signers: each signer's name, role, sign_order, status, signed_at and declined_at, with no text and no addresses.

Workflows: the person it is for, and the people every time

A workflow names its roles once, and each start fills them (Waivers and workflows). GET /v1/workflows lists them as signer_roles, each with a label, a role and an order:

• The participant (participant: true, one per workflow): whoever the start is for. Their link comes back in the start's answer and is not emailed, because they are at the form, the tablet or your own page already.
• Fixed people, with an email and a full_name: a manager who countersigns every waiver. Each is emailed their link the moment a document starts.

The workflow's own sequential decides the order, as on a document. Roles are set in the dashboard under Forms & QR, which offers the person it is for and up to two fixed people; the API reads a workflow and starts one, and has no route that changes one.

Somebody who signs only after an answer

A fixed person can sign only when the form's answers say so: a guardian when the guest is under 18, a manager when the hire is over $10,000. Under Questions to ask first, add the question and choose what kind of answer it takes (a tick box, a date of birth, a number, one of a list). Under Advanced: edit as text the same questions are one per line:

under_18 | The guest is under 18 | checkbox
dob      | Date of birth | birthdate
total    | Hire total | number
craft    | Craft | choice: Kayak, Canoe, Paddleboard

and under the person, choose They sign only if the question, what about its answer, and the answer. In signer_roles it is the role's show_if, the same shape a question's condition has (questions and fields): one rule, or several joined by all or any, in groups if need be, each about one of the form's own questions. The dashboard offers only if and unless with one rule; a condition with more, written through the API, is kept as it is when the workflow is saved there.

It is decided when the document starts, from the answers as they were given, each checked first as a template's answer is: a date of birth that is not a date refuses the start, naming the question, rather than leaving a guardian off. A person whose condition is not met is not on the document at all: no link, no reminder, nobody waiting for them. The start's answer lists them under not_needed, and so does the document's sent event. The person the form is for always signs, so they cannot have a condition, and somebody other than those copied in has to sign whatever the answers; the dashboard says so when a workflow is saved.

One person in two roles

A role with "self": true is the participant again: a sole proprietor signing for the business and again as personal guarantor. The start makes a second signer at the same address, named with the role's label after the person's name (Dana Reyes (Guarantor)), and emails it its own link; in a sequential workflow that link waits for the first signature.

{ "signers": [
    { "full_name": "Dana Reyes", "email": "dana@example.signsealer.com", "sign_order": 1 },
    { "full_name": "Dana Reyes (Guarantor)", "email": "dana@example.signsealer.com", "sign_order": 2 }
  ] }

When everybody in a booking's party signs

A booking for three is three people taking the risk, and the person who booked cannot accept it for the other two. A workflow with each_person_signs on GET /v1/workflows, started with persons above one in values or fields (the WordPress plugin's bookings send it), records the party on the document, and the start answers party_size, at most twenty. The form's own page asks How many people are signing, including you? when nothing on it asks for persons already, so a QR code or a website link starts a party too.

• The person who booked describes the others first. They cannot sign until they have, and it is done on the signing page, not over the API: send them to their link. On GET /v1/sign/{token}, party says lead, how many are still_to_add, the others added, and for somebody added, added_by.
• Each adult signs their own link. One added with an email address, or a number that has agreed to the business's texts, is sent their own link, and the person who booked never sees it. One we cannot reach is handed their link by the person who booked, which goes on the trail as link_shown; that signature is assured as party_link and the certificate says who handed it out (Evidence and certificates).
• Or one link for the whole party. The person who booked can share a single party link, under /p/ on the business's signing host; each person opens it, picks their place, gives their own address or number and goes on to their own link. The workflow can ask them to confirm a code sent there first.
• A child is not a signer. An adult signs for them, answers the template's per-child questions about each child, and ticks that they are the child's parent or legal guardian.

The document cannot complete until every place in the party is taken and signed. A party's link is sent to one address at most three times a day (Limits and paging).

Or a document each. With party_documents set to each (What the party signs under Forms & QR), every adult the person who booked adds gets a document of their own, made from the first: the same template version and answers, their own name in it, the same last day, and anybody else the form has sign it, such as the business's countersignature. A parent who is not in the party has one too, and signs for their child on it; a child goes on the document of whoever signs for them. Each document completes on its own, and each is a signing. The links, the party link and party on the signing link work as above, across all of them.

Reminders

The automatic one. Each signer and approver who has not signed is sent one reminder, with a fresh link, once the document has been out for the workflow's Remind after days, or the business's own setting, which is three days unless it has been changed; Never, or zero, turns it off. It skips a witness, an embedded signer, a document that has expired, anybody it has no way to reach, and anybody who has already had a reminder of any kind. In a sequential document it goes only to the people whose step it is.

On demand. POST /v1/documents/{id}/signers/{signer}/remind sends a fresh link to one person who has not signed, and the link they had stops working. It is refused for a cc, somebody who has signed or declined, a document that is not out for signature, and past the limits in Limits and paging, and in every refusal their link is left as it was. by in the answer is the road it went by. Either kind is signing.reminded.

Declining

A signer who will not sign says so: I would rather not sign this on the page, or POST /v1/sign/{token}/decline with a reason of 1 to 500 characters. One decline closes the whole document: its status is declined, every other link says This document was declined and is closed., no more reminders go, and a packet holding it is blocked rather than waiting. signing.declined carries the reason as signer.decline_reason.

Somebody who has signed cannot decline, because a signature is withdrawn by agreement, not by declining; nor can a cc, who has nothing to decline. To try again, prepare and send a new document.

Changing who signs

There is no route to change, replace or remove a signer once a document has gone out. A wrong address is fixed by voiding the document with a reason, POST /v1/documents/{id}/void, and sending a new one; a document everybody has signed cannot be voided. A lost link is not a wrong address: .../remind sends a fresh one, and POST /v1/documents/{id}/signers/{signer}/embed hands you one to show.

Following it

Each of these is a webhook (Webhooks), and every one about a person carries signer with their role, sign_order and status.

Between events, GET /v1/documents answers signers, signed and waiting_on for each document, and GET /v1/documents/{id}/signers each person's step and state.

A link sent with POST /v1/documents/{id}/send lasts until the document's expires_at, or thirty days when it has none. Only a document with an expires_at expires as a whole and sends signing.expired; a link running out of its thirty days sends nothing.