Observers
CC-style spectators on a signing request — notified when it goes out and when every signer has signed. They never sign.
An observer is a CC-style recipient on a signing request. They never sign; they get at most two emails:
- On dispatch: when the first signer is invited:
"X is collecting signatures on Y." No attachment and no link to the
document. Not sent with
send_emails: false, which silences this notice along with the invitations. - At completion: when every signer has signed: the final tamper-evident PDF + the audit certificate, which is always in English. Nothing is sent when a signer declined, was withdrawn or expired: such a document never completes.
Observers are workspace-scoped CCs, distinct from signers. They get no signing URL, no token, no field placement.
Adding observers
{
"observer_emails": [
"outside-counsel@law-firm.com",
"compliance@acme.com"
]
}Pass on
POST /v1/signing-requests, the only
create call that takes observers (instantiate and confirm do not). Up to
20 observers per document, counted before duplicates are removed; more
entries are a 400 invalid_request. Each entry is a plain address string,
at most 254 characters; there is no name or language per observer. Send
addresses without surrounding spaces: they are checked before anything else
happens, so " office@firm.ch", a display-name form
("Office" <office@firm.ch>) or a non-ASCII domain (send its xn--…
punycode form) is a 400 invalid_request. Accepted addresses are
lower-cased and de-duplicated, and the response's observers lists what was
stored. The list cannot be changed after the create.
The request key is observer_emails; observers is only the response key.
In a multipart body, send the array as a JSON-encoded string.
An observer who is also on the document
An address in observer_emails stays on the list even when it is also a
signer or the document's sender (the user who created the API key). That
person gets the dispatch notice next to their own invitation, but only
one email at completion:
| The observer is also… | At completion they receive |
|---|---|
| The signer whose signature completed the document | Their own signer email, not the observer copy |
| A signer who signed earlier | The observer copy only |
| The sender | The sender's own completion email, not the observer copy |
When are they emailed?
| Event | Observer notification |
|---|---|
| First signer is invited | "X is collecting signatures…", to all observers in one message, in the language (locale) of that first signer |
| Subsequent signers are invited | No notification (the dispatch note already went out) |
| Each signer signs | No notification (saved for completion) |
| Every signer has signed | "Completed" with the signed PDF + the audit certificate, to all observers in one message, in the language of the signer whose signature completed the document. The certificate is in English. |
| A signer declines, is withdrawn or expires | No notification, then or later: the document never completes |
Treat document.completed, or
GET /v1/documents/{id} →
status: "signed", as the proof of completion, never the observer email.
All three follow one rule: every signer signed.
Observers don't see real-time intermediate events, and there are no
observer webhooks. If you want that level of detail, register a
webhook: the workspace webhook fires
signing_request.signed per signer, plus document.completed at the end.
Both observer emails are on the audit trail, with the addresses in
meta.observers: observer_notified on the first invited signer's
request and observer_completed on the completing signer's request
(GET /v1/signing-requests/{id} → auditEvents). The audit certificate
lists no observer addresses.
Use cases
- Outside counsel that needs the final signed contract for the firm's file.
- Compliance / risk that wants the audit certificate for an archive without becoming a signer.
- Account exec who needs a trigger to update the CRM but isn't party to the contract.
- A shared mailbox such as a secretariat: an observer is an address, not an account.
What observers don't do
- Sign: they receive emails, not signing URLs.
- Receive reminders, a note per signature, or a declined, withdrawn or expired notice.
- Place fields: every field is placed by the create call itself (anchor markers, explicit coordinates or an appended signature page; see Placement modes).
- Edit observers: once a signing request is dispatched the observer list is fixed for that document.