Skip to main content
A signing link is a bearer credential: whoever holds the email holds the document. Signer verification adds one step for a recipient you choose. Before the document opens, they are emailed a 6-digit code and must enter it.

​
Turning it on

Set verification_method on a recipient when you create the envelope, with POST /api/v1/envelopes, a row of POST /api/v1/envelopes/batches, or POST /api/v1/envelopes/one-off:
  • none is the default. A request that does not name the field creates the recipient it always did.
  • email_code asks for a code sent to the recipient’s email.
  • It is decided per recipient, so one envelope can ask one signer for a code and not another. A template has no setting for it: the request decides, every time.
  • It is fixed once the envelope is sent, like the rest of the recipient. See what cannot change after sending.
  • Every recipient the API describes carries verification_method, so you can read back what you asked for with GET /api/v1/envelopes/{envelopeId}.
sms_code is in the published list and is not available yet: codes by text message come later, and mobile is reserved for them.

​
Who cannot be asked

  • An embedded recipient cannot be asked for an email code. Vumasign never emails an embedded recipient, so the code could never reach them. Your application signed them in, and that is the check. Use none.
  • A recipient on a cc role cannot be asked for anything. A copied-in reader never opens a signing page, so there is nothing for them to verify.
Both are refused before anything is created. See the refusals below.

​
What the signer sees

When they open their link, they see a short screen instead of the document. It names who sent it and the address the code will go to, partly hidden. They choose to have the code emailed, then type it in.
  • A code can be entered for 10 minutes after it is sent.
  • A new code can be asked for after 30 seconds. Asking for one replaces the last.
  • They are asked once per signing session, not once per page. The session lasts 4 hours in that browser, and never longer than the link itself. After that, or in another browser, they are asked again.
  • Each code allows 5 tries. Once 3 codes have been used up within 1 hour, the recipient is paused: no further code is sent for up to 1 hour, and the screen says when they can try again. The pause ends by itself, and nobody has to lift it. A new link ends it sooner: the sender’s resend from the dashboard, or a reminder, each carry one.
  • The pause is not the only limit. How many codes one link, one address or one network can be sent over time is limited too. Those limits also lift by themselves, but a new link does not lift the ones on the address or the network.
Every signing act checks the session again, not just the first page. A recipient who has not entered a code can save nothing, sign nothing and download nothing.

​
What the certificate says

The certificate of completion states a code only where the audit trail records the code being entered. It does not read the setting on the recipient to decide. So a recipient who was asked for a code and never signed is not described as verified, and a signature always names the verification that let it happen. Where the audit trail records a one-time code being entered, the line goes on to say so — for example “Email link with expiring token, plus a one-time code by email to j•••@example.com, entered 01 Oct 2026, 12:02:11”. On a test document, whose code is shown on screen rather than sent, it reads “Email link with expiring token, plus a one-time code shown on screen (test document: nothing was sent), entered 01 Oct 2026, 12:02:11”. An emailed code shows that the person signing had the mailbox when they signed, not only when the link was sent. It is not a second factor: it reaches the same mailbox as the link.

​
Refusals

Each refusal names the recipient by its path in your request, for example recipients[1] or rows[3].recipients[0]. Nothing is created, and in a batch no row is created.
  • recipient_verification_not_allowed: an email code for an embedded recipient, or any code for a cc.
  • recipient_verification_unavailable: sms_code, until codes by text message are available.
  • recipient_mobile_unused: a mobile was given. No method that sends to one is available yet, so it is refused rather than stored.

​
The webhook

Subscribe to recipient.verification_locked to hear when a recipient is paused. Its body carries recipient_id and locked_until, the time the pause ends. That is not a promise that a code will be sent then: the other limits above can still refuse one, and they publish nothing. It fires once per pause, and not for a recipient who has already signed and is only entering a code to download what they signed. It is the only verification event published: wrong codes and codes sent stay in the audit trail, and you hear that the recipient got in from recipient.completed when they finish. See webhooks for the body and how to verify it. A paused embedded recipient would be stuck with only you able to help, which is why the event exists. In this release an embedded recipient cannot be asked for a code, so every paused recipient is one who was emailed: they can wait, or the sender can resend their invitation from the dashboard.