Turning it on
It is decided per recipient, so one envelope can ask one signer for a code and not another. A template made on the dashboard can set a default for each role; whoever sends an envelope from it on the dashboard starts from that default and can change it.From the dashboard
Who signs is about the document: who each person is and what they do. How each one is confirmed is asked when you send. Press Next: send and the Send step lists every person who signs, approves or witnesses, each with a control named How we confirm it’s them. It has four choices side by side, each with the level the certificate shows for it:- Signing link only: the link in their invitation opens the document. It has no level.
- Email code, Level 1: they are emailed a code before the document opens.
- Mobile code, Level 2: the code is sent to their phone.
- Identity check, Level 3: a code to their phone, then their ID or passport and a live selfie, on Team, Business and API at R59 a signer. See the identity check. On the Free plan it is shown locked, with "Available on paid plans" and a Change plan link.
- With Mobile code or Identity check, the person’s card gets a Their South African mobile number box. It takes a South African mobile number in the usual ways of writing one, and shows it back as it will be used. Send stays closed until every such person has one. Under the choice, the dashboard shows how many mobile codes your plan includes and how many have been used this month.
- Add job titles or companies, under the cards, adds a job title and a company box for each person, on the same step.
- On a template, each role in Who signs has one line, Starts on: the check every envelope sent from the template starts each person on. It offers the three choices a role may start on; Identity check (chosen at send) is listed and cannot be picked, so no send of a template asks for an identity check unless the sender chooses it, person by person, on the Send step. A template holds no phone numbers, so each send asks for the mobile. A role added to a template starts on the organisation’s default.
- Sending from a template, you name the people first, then the same Send step opens with each person on their role’s Starts on. Changing one there changes that send only.
- A group (“any one of these people”) has one card on the Send step and one choice for the whole group. When that choice needs a mobile, each of the group’s people gets a Their South African mobile number box, since any of them may be the one who signs.
- A role pre-signed under a standing authorisation is listed on the Send step as pre-signed, with no control: nobody is asked for a code for it.
- A person who is copied in has no such control: a copy is never asked, for the reason below.
- An envelope made with the API shows what the API asked for, and saving it keeps that unless you change it. The organisation’s default is the dashboard’s: a recipient the API creates without naming a method is asked for nothing, as below.
With the API
Setverification_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:
noneis the default. A request that does not name the field creates the recipient it always did.email_codeasks for a code sent to the recipient’semail.mobile_codeasks for a code sent to the recipient’smobile, which is then required: on WhatsApp first, and by SMS when WhatsApp cannot reach them. It must be a South African mobile; it may be written with the country code or with a leading zero, with or without spaces, and it is stored and returned with the country code.sms_code, the name this method had before it went on WhatsApp, is still accepted and means exactly the same. It is deprecated: every read returnsmobile_code.- 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_methodandmobile, so you can read back what you asked for withGET /api/v1/envelopes/{envelopeId}. identity_checkasks for an identity check, with its options in a field of the same name. See the identity check below.
The mobile number
A mobile is kept only for a recipient asked for a code on their phone, and it is used for nothing but that code: no invitation, reminder or notice is ever sent to it. It is your own data, so your envelope reads return it in full; the signer’s screen, the envelope’s history, the certificate and webhooks show it partly hidden. A wrong number is fixed by correcting the recipient, which asks for the right one. To deliver the code, the number and the code are passed to SMSPortal, our messaging provider, and through it to WhatsApp (Meta) when the code goes on WhatsApp, or to the mobile network when it goes by SMS. They use it for that delivery only.The identity check
An identity check asks the signer to show who they are, not only that they hold a mailbox or a phone. It always starts with a code to their phone, exactly as Mobile code does, so it needs their mobile number too. Then, once per envelope, VerifyNow, our identity-check provider, checks their ID document and a live selfie taken with their phone’s camera.An identity check on a test envelope, a test key’s or one sent with Send as a test, uses VerifyNow’s
sandbox, which returns sample results and costs nothing. If identity checks are not switched on for live
envelopes, a live envelope that names one is refused when it is sent, with
identity_check_not_live, and the Send step says "Identity check isn’t switched on for live sends yet. Turn on Send as a test to use it, or choose another check."What the signer does
- They enter the code sent to their phone.
- If they opened the link on a computer, they move to their phone: by scanning a QR code, or by asking for the link to be sent to the number they have just confirmed. The check needs a phone with a camera, and photos are taken with the live camera only; nothing is uploaded from a gallery. These screens, and the message that sends the link, name the brand the envelope was sent under, as the invitation did.
- They agree, on a screen of its own, to their photos being used for the check. They may say no, or say they cannot use a camera; either way they are told to contact you.
- They photograph their South African ID (a Smart ID card, front and back, or a green ID book) or their passport, and then take a selfie.
- With an SA ID, the number is read from the document, and the selfie is matched to the Home Affairs photo for that number. With a passport, the passport is checked for signs of tampering, copying or screen capture, and the selfie is matched to the passport’s own photo. A passport is not checked against the issuing authority’s records.
Choosing it on the dashboard
On the Send step, choose Identity check on a person’s card. It is offered on Team, Business and API, and on the Free plan it is shown locked, with "Available on paid plans" and Change plan. Under the person’s mobile, a line says which documents they may use, and Options sets two things:- Which documents: SA ID or passport (the default), SA ID only, or Passport only.
- The ID number you expect, if you have it: an SA ID number, checked as you type, or with Passport only a passport number and its issuing country. If the ID they show has a different number, the check stops, nothing is charged, and you are told. With an expected number, they can use only the document of its kind. Once saved, the number is shown only by its last digits: it is never stored whole.
Asking for it with the API
routesiseither(the default),sa_idorpassport.expected_idis optional:{ "kind": "sa_id", "number": … }, or{ "kind": "passport", "number": …, "country": … }with the issuing country’s three-letter code, such asZAForZWE. An SA ID number is checked when the envelope is created.- The number is never stored or returned. Every read returns that field with
routes,expected_id: { kind, masked, country }andoutcome, ornullfor a recipient on another method. - It is refused on a row of a batch and on a
cc. An embedded recipient may be asked for one: the check runs on their phone, never inside your iframe, and must finish inside the embedded session (see the embedded signing guide).
Reading the result
identity_check.outcome on the envelope is null until the check finishes.
Then it says how it ended:
expected_id_matched is true only when you gave an expected_id and the document’s number matched it, and
false when you gave none. An expected number holds the signer to its own kind of document whatever routes
says: with routes either and an SA ID number, they may use only an SA ID,
and a passport is refused before it is checked. To make the routes say so too, give
sa_id (or passport) with the expected_id.
A pass is not a match on the name: name_match never fails the check, so read expected_id_matched and
name_match as well as status before you rely on who signed.
A check that cannot finish reads "status": "failed" with the same reason as the
recipient.identity_check_failed webhook, and null for everything it never reached. The
outcome never carries the ID or passport number, a score, a photo or the name on the document.
What it costs
R59 a signer, charged once they reach the face match, whatever its result, and at most once per signer per envelope. A second try is included, and so is a check that carries on in a new embedded session after the last one ran out. Nothing is charged for a check that stops before the face match: an unreadable document, an ID that did not match the number you gave, a missing Home Affairs record, an outage, or a signer who cannot use a camera. Card customers see it as a line on the month-end card charge, and Plan and usage in Settings shows how many there have been this month. It is never charged on a test envelope.Switching to a mobile code
On a sent envelope, the recipients list shows each identity check’s state: Not started, Checking with the try they are on, Identity confirmed, Couldn’t confirm, ID didn’t match, Can’t use a camera or Checks unavailable. Until they have signed, Switch to mobile code moves them to a mobile code instead, after you confirm it in the list (Keep identity check leaves it as it was). They are emailed a new signing link and the old one stops working; an embedded recipient is emailed nothing and carries on in your application, asked for a mobile code. The envelope’s history keeps the identity check that was asked for, and the certificate states the mobile code. A charge already made is not refunded.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. If you want one more, use
mobile_code; otherwisenone. - A recipient on a
ccrole cannot be asked for anything. A copied-in reader never opens a signing page, so there is nothing for them to verify. The API refuses both before anything is created: see the refusals below. The dashboard does not offer them.
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 or number the code will go to, partly hidden. They choose to have the code sent, then type it in. If the member who sent it has since left your organisation, the screen and the code name your organisation instead, so the recipient can still get in: see who the emails name.- 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. For a recipient whose status is sent or opened, on an envelope still out for signature, a new link ends it sooner: the sender’s resend from the dashboard, or a reminder, each carry one. Neither is sent once the member who sent the envelope has left your organisation. A recipient who has already finished and is entering a code only to download what they signed is sent no new link, so they can only wait.
- 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.
A code sent to their phone
It goes on WhatsApp first, as WhatsApp’s own verification message from Vumasign OTP: it carries the code, a button that copies it, and nothing else, with no link and no document title. WhatsApp shows such a code only on the phone that holds the account, not on WhatsApp on a computer. On a recent iPhone, the keyboard can offer it straight into the code box. The same code is sent by SMS, never a new one, when WhatsApp cannot deliver it:- at once, when WhatsApp refuses it (the number has no WhatsApp, for instance);
- when WhatsApp has not reported it delivered within 20 seconds, while the signer’s screen is open; and
- when the signer chooses Send by text instead, which the screen offers once per code.
On a test document
A test document (a test key’s, or one sent with Send as a test) sends no WhatsApp message and no text. The code is shown on the signer’s screen instead, inside the test notice, so the whole flow can be tried without a phone and without using any of your plan’s mobile codes. It is never a fixed code. A code by email on a test document is sent for real, to the test addresses you have confirmed.Where you see it
On a sent envelope, the recipients list marks each person who was asked with Asked for an email code or Asked for a mobile code. A person who is paused reads Verification paused until and the time, in South African time, with how to lift it. It lifts by itself; for a recipient whose status is sent or opened, on an envelope still out for signature, sending their invitation again lifts it sooner, and the line says so only then. Anyone else can only wait. The envelope’s history records each step in words, including which way a code to a phone went: on WhatsApp, by SMS, or both. Where a line names the address or number a code went to, it is partly hidden, as it is on the signer’s screen. A code itself is never shown. Every line it can show:When the session ends mid-document
The session can end while the signer has the document open. The next thing they do (saving, signing, or an automatic save) is refused, and the page takes them to the code screen. What they had typed in that browser tab is put back once they have entered the new code in the same tab, unless the same answer was saved differently in the meantime, from another tab, in which case the saved one stands. A signature comes back together with the signature it was adopted as, drawn, uploaded or typed, and in the same handwriting style; if that cannot be restored, the signer adopts it again. Anything already saved was never at risk.Handing it over
A signer who passes the document to somebody else, and a sender who corrects a recipient, keep the check: the new person is asked for the same kind of code. For a code to a phone the form asks for the new person’s own mobile. It is never copied from the person they replace.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. For a code sent to a phone, it names the way the code went.
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”. A mobile code names the way it actually went: “Email link with expiring token, plus a one-time code sent on WhatsApp to +27 •• ••• •567, entered 01 Oct 2026, 12:02:11”, “Email link with expiring token, plus a one-time code by SMS to +27 •• ••• •567, entered 01 Oct 2026, 12:02:11”, or, when WhatsApp could not reach the signer in time and the same code was texted, “Email link with expiring token, plus a one-time code sent on WhatsApp, then by SMS, to +27 •• ••• •567, entered 01 Oct 2026, 12:02:11”; and where the audit trail cannot say which of the two carried it, “Email link with expiring token, plus a one-time code sent on WhatsApp or by SMS to +27 •• ••• •567, 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.
A code sent to a phone shows that whoever signed could read messages for that number at that time, on
WhatsApp or by SMS, and holds the link. It does not show that they are the subscriber of the number, that the
number was not ported or moved to another SIM, or that the phone was not shared. Texts can be intercepted on
the network, and South African banks treat them as a weak check for that reason. The certificate never calls
either kind of code an identity check.
An identity check is stated in its own panel on the certificate, naming which document it used, only where
the audit trail records it passing, and on a test document it says that no real check was made. The panel
says what was checked and by whom; it never shows a photo. An identity check strengthens the evidence of who
signed; it does not change the signature’s legal category.
Codes to a phone and your plan
Codes by email are free on every plan. Codes to a phone cost money to send, so each plan includes a number of them each month, counted from the audit trail: each code counts once, whether it went on WhatsApp, by SMS, or on WhatsApp and then by SMS, delivered or not. Codes on test documents never count.
On a plan with no price past its allowance, a send is refused with
sms_allowance_exhausted
when the people it would send a code to their phone, added to the codes already sent this month and to the
people on envelopes already out who are still to be sent one, would pass the allowance; you can
send those recipients an email code or no code instead. A signer can still ask for a new code once their
envelope has gone out, so on that plan new codes stop once 20 have been sent in the month,
and the signer is asked to contact the sender. On every plan, no more than 300 codes are sent
to phones for one organisation in a day, as a safety limit; past your allowance, a paid plan is otherwise
never stopped. Plan and usage in Settings shows how many have been sent this month.
Refusals
Each refusal names the recipient by its path in your request, for examplerecipients[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 acc.recipient_mobile_required:mobile_codewith nomobile.recipient_mobile_invalid: amobilethat is not a mobile number a code can be sent to.recipient_mobile_unsupported_country: a mobile outside South Africa. Codes can be sent to phones only in South Africa for now.recipient_mobile_unused: amobilewas given for a recipient whose code does not go to a phone. It is refused rather than stored.
An identity check has refusals of its own:
identity_check_requires_paid_plan on the
Free plan or for a card customer with no card on file, when the envelope is created and
again when it is sent; identity_check_not_live when a live envelope naming one is sent;
recipient_identity_check_not_allowed, recipient_identity_routes_invalid and
recipient_expected_id_invalid. The number you sent is never quoted back.
The webhook
Subscribe torecipient.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, recipient.identity_verified and recipient.identity_check_failed are the only verification events 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.
Subscribe to recipient.identity_check_failed to hear when a recipient’s identity check cannot
finish. Its reason is attempts_exhausted, id_mismatch or cannot_use_camera, beside recipient_id;
it carries no number, name or score. It fires once per recipient. The remedy, switching them to a mobile code
or correcting the signer, is made in the dashboard.
Subscribe to recipient.identity_verified to hear when a recipient passes, before they sign.
It fires once per recipient and carries ids only: read the envelope for identity_check.outcome.
A paused embedded recipient is stuck with only you able to help, which is why the event exists: an
embedded recipient whose code goes to their phone can be paused like anyone else. An emailed recipient can
wait; while their status is sent or opened and the envelope is still out for signature, the sender
can also resend their invitation from the dashboard.