Skip to main content
Every workflow is assembled from the step types on this page. Which of them your journey runs, in what order and with which settings, is configured with us during onboarding - so read this as the menu: what each type asks of the user, what it checks, and what it gives the rest of the journey. Whatever the mix, every step reports the same envelope; Reading the result is the field-by-field reference for reading one. The value in backticks under each name is the type the API reports for that step. To see the mix configured for you rather than the menu, read the workflow itself with GET /workflows/{workflow_key}. It returns the workflow’s mode - whether the person walks a journey themselves or you supply everything over the API - and every step it can present, in the order they are answered, each with the condition that gates it and an intake saying how it is answered. Where a journey is presented in named parts, it also returns groups - the headings, in the order they are met - and each step that belongs to one names it in group.
A workflow’s mode, its step keys and each step’s intake are stable. The rest is a reference view of configuration we hold and maintain: which steps a workflow declares, how each is configured under settings, and the conditions that gate them all change without notice as your journey is tuned, each change a new version that only the verifications created after it run. A step’s slots reach you twice: intake names the keys and the shapes you address a document by, and settings words the same slots as the person providing them is asked for them. Address a document by what intake says. Read the workflow to understand a journey; the stable thing to integrate with is the steps array on a verification record, described in Reading the result.
On a staged workflow, a step is answered from what you upload to its slots and send for its values. Three types are answered by the person being verified rather than by you: selfie and premises-photos are captured live through a camera, and digilocker is a consent granted on the issuer’s own screens. Only a hosted workflow declares one of those, and review likewise, so a staged workflow you read never contains them. Four properties do the composing:
  • Required or optional. The user may decline an optional step, and the record states that they did.
  • Conditional. A step can be included only for the users it concerns: extra proof only when a check did not pass, a second account only when your context asks for one.
  • Grouped. Consecutive steps can be presented under one heading - the several that together establish registration details, say - so a long journey reads as a few named parts rather than one queue.
  • Fed by earlier steps. A step can read what an earlier one established - the names a GST registration is held under can be the names the bank account must be registered in. This is how the types below combine into one coherent journey.

​
Form

form Typed fields you define: text, number, date, yes/no, a choice from options you list, or a postal address. A text field can be held to a format - PAN, GSTIN, IFSC, mobile, email, or PIN code - and a field can be pre-filled from a value established earlier, with the user confirming or correcting it. A value held to a format is read with surrounding spaces dropped, and a PAN, GSTIN or IFSC in any case, so abcpe1234f is accepted and published as ABCPE1234F. An optional field sent empty, or as nothing but spaces, is a field left blank. A number sent for a text field is read as the text a person would type for it, so 411001 or 411001.0 sent for a PIN code is the PIN code "411001". An address field asks for an address in India in its parts and publishes it as one object, in the shape a GST certificate states a place of business in: street, city, state, country and postal_code. Every part has to be given, state is one of the states and union territories the API reference lists, postal_code is a six-digit PIN code, and country is India. Plumb a GST certificate’s primary_business_address into one to pre-fill it with the registered place, or another form’s address field to pre-fill it with what the user gave there. A field can be asked on some journeys and not others. Each gate on it names an earlier field of the same form, or a value the form is given, together with the values of that key which ask for this field; a field carrying several gates is asked when every one of them holds. A field the journey never asked publishes nothing, exactly as an optional field left blank does. Fields that can never both be asked may publish under one name, which is how a single name carries whichever of them the journey reached. Ask a company for the registration details a company has and an individual for theirs, and read one value back whichever way the journey went. A form waits for the step supplying a value it reads to settle, and asks the rest of its fields whether or not that value arrived: a check that establishes nothing costs the applicant only the fields that read it. A form the journey leaves nothing to ask is not part of that journey, the same way a step whose condition did not hold is not. The answers are published under your field names, for later steps and for your own systems. Only a hosted workflow asks a form: it writes down what the person tells you and establishes nothing about it, so a workflow you supply the values for sends them as context instead.

​
Documents

documents Files gathered into named slots you define. Each slot names the kinds of document that satisfy it, and each kind says how it arrives: PDFs, images or either, one file or up to a count. The step checks presence and file type and nothing more: use it to collect paperwork your own reviewers will read. Only a hosted workflow gathers documents this way. It establishes nothing about what the files hold, so a workflow you supply the files for has nothing to learn from one; attach those files to the checks that read them instead.

​
Parsed documents

parsed-documents Several documents in one step, each read and held to what your workflow says about it. A slot names the kind of document that satisfies it, or a choice of kinds where either would do, and whoever provides the files says which they sent - so each document is read as what it is, and one sent as something else comes back unreadable rather than misread. What each kind is held to is configured for you. A date the document runs to can be required to be still in force, and to report itself when it is close to running out; a name it is printed in can be scored against a name the step is given; and an identifier it carries can be required to be exactly one the step is given. A check that fails can either fail the step or be reported on a step that still passes, whichever the requirement warrants. Where the journey holds nothing to compare against, or the document prints no such value, the step publishes the check as one that could not be made rather than as one that passed. A name or an identifier a check reads comes from wherever your workflow has it: a value an earlier step established, a field of the context you supplied when creating the verification, or one written into the workflow. A check names the value it held the document to, so a reading carries what the document had to say beside what it said. Publishes every document as it was read, each with the checks it was held to and how each came out. Expiry is judged on the day the step is judged, so a registration that lapses between one reading and the next has lapsed.

​
PAN card

pan-card The user provides a clear photo or PDF scan of a PAN card. The card is read and checked against the PAN registry, and the workflow can additionally hold it to a specific PAN, to the PAN behind a GSTIN established earlier, or to a roster of named people - so the card is not just genuine but the right person’s. Publishes the PAN, the holder’s name, the date of birth or incorporation the card prints, and the card image, which a selfie step can match a face against, along with the registry’s own word on the PAN: whether it is operative, and whether an Aadhaar is seeded against it, which only a PAN held by a person can be.

​
GST certificate

gst-certificate The user uploads their GST registration certificate, as one PDF or a photo per page. The certificate is read and confirmed against the GST registry, and passes when the registry holds the registration as active. One still active pending verification passes as well, and carries the gap gst-pending-verification, since the GST department has not finished verifying it. Publishes the registered identity - GSTIN, legal and trade names, registered addresses, business constitution, the promoters the certificate names, and the business PAN - which is the material most other checks are held against. It also publishes the rest of what the registration states about the business: its taxpayer type, whether e-invoicing is mandated for it, the turnover slab it is registered in, its authorised signatories, the activities it is registered to carry on, the HSN and SAC codes covering the goods and services it deals in, and its return filing history - every GST return the registry holds, of whatever type and period, each with the status and filing date the registry states. Where your workflow asks for it, the step also reads the contact registered against the GSTIN and publishes it as business_email and business_mobile. A step that does not ask carries null in both, as does one that asks against a registration holding no contact. Where you already know which registration you want a certificate for, the step can be given the GSTIN, and a certificate for any other one fails it. It can be given a PAN instead, which asks for a certificate of whichever registration that PAN holds, since a GSTIN carries its holder’s PAN. Either is read off the certificate itself, so a certificate for another business is answered as the wrong document rather than checked against the registry. Where your workflow has established what the business is registered as, the step can be given that constitution and holds the registration to it. A certificate the registry holds under any other constitution fails the step, however sound the registration behind it is. Give it one of the constitutions the registry issues, spelled as the registry spells them: Sole Proprietorship, Partnership, Hindu Undivided Family, Private Limited Company, Public Limited Company, One Person Company, Limited Liability Partnership, Foreign Limited Liability Partnership, Foreign Company, Unlimited Company, Public Sector Undertaking, Society/ Club/ Trust/ AOP, Government Department, Local Authority, Statutory Body, Trust, Others. Whichever of the three the step is given is shown in the ask, so a business holding a registration in each state it operates in is told which one to reach for rather than finding out by uploading the wrong one. A workflow whose subjects are not all GST registered can set ask_if_registered, and the step puts that question before anything is uploaded. A business that is registered uploads its certificate as usual, and one that is not declines the step, which the record states the way it states any decline. A step that asks sets required to false, and later steps branch on it with a step-outcome condition of passed or declined.

​
Bank account

bank-account The user types the account number and IFSC, or uploads a document evidencing the account. Which documents count is per your workflow: any of a bank statement, a cancelled cheque and a bank letter, or only the ones you name. Whichever way they answer is what gets checked, directly with the bank - without moving money, or with a ₹1 test deposit, per your workflow. The account can be required to be registered in one of a set of names, such as the names the GST step established. Publishes the account as the bank states it, which can differ from what was typed. The bank and the branch the IFSC belongs to are published when the check used the ₹1 test deposit, which names them, and when the user uploaded a document, which prints both on its face. An account typed in and checked without moving money carries null for both.

​
Udyam

udyam The user uploads their Udyam registration certificate, which is read for the registration number and the enterprise it was issued to, and the number is then confirmed with the Udyam registry. Publishes the registration as the registry states it.

​
PCB certificate

pcb-certificate The user uploads the consent order their state pollution control board granted them, as one PDF of the whole order. No board publishes a register a verification can read, so the certificate is itself the source: it is read for its registration number, the business it was issued to, the board that issued it and the period it runs for, and the step establishes that it is still within that period and that it was issued to the business being verified rather than to another one. The names it may be in are the ones your workflow gives it, such as the legal and trade names a GST registration is held under, and the certificate is scored against whichever it comes closest to. A board issues a consent in the registered name the business applied under: a company’s is in its legal name, while a sole proprietorship’s may be in the proprietor’s own name or in the name the business trades as. A name far enough from every one of them to be a different business fails the step; one that is close without matching passes and reports its score, so a near miss is left for a person to weigh. Which name it came closest to is published by its tag, since matching a trade name is a different finding from matching a legal name at the same score. Expiry is judged on the day the step is judged, so a certificate that lapses between one reading and the next has lapsed. Publishes what the certificate states. A workflow can give the step no names, and the certificate is then judged on its validity period alone. Names it is given are always checked: a step that reads them from an earlier one is not asked for until that step has published them, an empty list or null given as a fixed value or as context is refused when the workflow is published or the verification is created, and an empty list that arrives from an earlier step fails the step with pcb-not-checkable.

​
Name match

name-match The cross-check that every document names the same party. Each check reads a name your workflow gives it - the holder a bank returned, the enterprise an Udyam registration is in - and scores it against a reference name, which is the name the business is anchored on. A check reading several names, as a GST registration does with its legal and trade names, is satisfied by whichever of them comes closest. A name far enough from the reference to be a different business fails the step; one that is close without matching passes and reports its score, so a near miss is left for a person to weigh. A check whose name never arrived is not scored and not held against the step, because the step that failed to establish it already says why. Every score is published, including on a step that failed, so the names that matched are on the record beside the one that did not.

​
DigiLocker

digilocker The user shares government documents straight from DigiLocker instead of uploading them, such as Aadhaar or PAN. You list the documents the consent asks for, and mark each one required or optional: a missing optional document still passes the step, with the gap noted on it. The holder can be checked against an expected PAN or a roster of named people. The PAN is checked when the holder shares it: one the workflow requires and the holder leaves out fails the step as a missing document, and one it does not require passes it with the gap, so a later step can ask for the PAN card instead, on a condition that the DigiLocker step published no pan. A PAN document shared without a number that can be read off it is held to the same rule under digilocker-pan-unreadable. A step given a PAN to check has to ask for the PAN document. Publishes the holder’s identity as the issuer states it, the Aadhaar number masked to its last four digits, photograph included. User-run only. The consent is granted by the holder signing in to DigiLocker themselves.

​
Selfie

selfie A camera capture, checked for liveness, matched against an identity document from an earlier step - typically the PAN card - or both. Either check can be turned off; with both off, the step simply collects the capture as evidence, such as the user holding their identity document in frame. User-run only. What the step reads is that the face was in front of the camera, which a stored image cannot evidence.

​
Premises photos

premises-photos Camera photos of the kinds you define - storefront, interior, signage - each captured with its location, resolved to an address at the moment the photo is taken and never supplied afterwards. Publishes the distinct places the photos were taken, for a later step to put to the user or hold up against the addresses on record. User-run only, because the location is fixed as the shutter falls and cannot be attached to a file afterwards.

​
Address tagging

address-tagging The user labels each of a set of addresses with tags you define - head office, warehouse, not in use. The addresses come from an earlier step, such as where the premises photos were taken. An address already on record, such as a GST-registered one, is recognised and tagged without asking, so the user is only asked about what could not be inferred. Publishes every address with its tag.

​
Address proof

address-proof Documents read as evidence that the business operates at addresses already established - a utility bill, a lease, whatever kinds your slots ask for. Each document is read for the premises address it states, optionally required to be in the business’s name, and you state how much the documents must prove between them: at least a number of the addresses, or every one. To collect documents without holding them to an address, ask for them with a documents step. The addresses it stands up have to name at least one place: an empty list or null given as a fixed value or as context is refused when the workflow is published or the verification is created. Publishes which addresses the documents stood up and what each document turned out to say.

​
Gate check

gate-check A question put to a system of your own, mid-journey, answered by what the journey should do there. Only a hosted workflow declares one, because what it decides is whether the person walking the journey goes on. It is always required, it cannot be put off, and it settles inline. Nor can it wait on a step the person can put off, or on one checked in the background, whether it reads that step itself or reads a step that does: one put off would leave the check undecided, and the person with nowhere to go, and one still being checked would leave their screen with nothing to show until it lands. The person meets it like any other step. Their screen answers it the moment they reach it, which puts the question to your system, and shows the step’s own title and content while your answer is on its way. It can be reached once the values it waits for have settled, and nothing after it is part of the journey until it has decided, so the person cannot go past it and cannot submit around it. That also puts several checks one at a time in the order the workflow declares them. A check is only ever asked by the person reaching it. If a value it was asked over changes, the check goes back to waiting, and it is asked again, as a new question, when the person next reaches it. Answering another step never asks it on the way, and neither does a background check settling.

​
What your system receives

A POST to the checks endpoint registered for the workflow, behind the same proof its callback goes behind, with X-Privue-Event: verification.check and the check’s name in X-Privue-Check. The body opens with the fields a callback opens with, from event to reference_user_id, and carries the question after them:

​
What you answer

Answer with an action, one of:
An action this step does not know is no answer, and the fallback below decides. A redirect_url on any action but redirect is ignored. A heading or wording too long to show is left out and the answer still stands, so a termination always ends the journey. reference_user_id is your own identifier for whatever the check matched, published on the step in your record as you sent it, a number kept as its text. It is never shown to the person walking the journey, since it names a record of yours, and no later step is given its value, though a condition can still test whether you sent one; title and content are what they see. An answer longer than 64 KB is not read as one. A redirect sends the person to its redirect_url only where that link is on the workflow’s list of places a person may be sent, which is the same list a return URL is held to. A redirect whose link is missing, or is not one on that list, still ends the journey, exactly as terminate would: the step publishes terminate, sends the person nowhere, and carries the gap gate-check-redirect-refused, whose details.cause says why: The record names the check that stopped it in gated_by_step, no later step or check is asked, and a gated run uses no credit. Where the workflow registers a callback, a verification.gated callback tells you the run was stopped, whether by your answer or by the fallback below.

​
When your system does not answer

Each check is tried as the checks endpoint’s registration says: by default twice, half a second apart. A timeout, a refused connection and a 5xx are tried again; an answer that says the request itself was wrong, such as 404, is not, and is a fault in how the check is asked rather than a missing answer, as below. Every attempt, its timeout and the pauses between them are spent while the person’s screen waits, so a registration is held to a minute across all of them. Where every attempt went unanswered, or your endpoint answered something that is not an answer, the step takes the fallback your workflow declares in when_unanswered. Every gate check declares one, as an action of its own and the wording that goes with it:
A title is at most 120 characters and a content at most 500, the same as an answer’s, and a workflow declaring a longer one is refused when it is published. The wording is fixed on the step when the check falls back and published on it just as your answer’s would be, so a record reads what the person was shown, and a later version of the workflow worded differently never changes it. Whichever of carry-on, terminate and redirect decides, the step passes carrying the gap gate-check-unanswered, which is how the record says your system did not answer, and its details.cause says why: hold settles on no decision. The person stays on the step, which reads as an error they can try again from, shown the title and content the hold declares where it declares them, and nothing after it is part of their journey. Each try puts the check to your system again, under the same request_id, so a hold is how the journey waits while you put right whatever kept your system from answering. The person is never moved on or stopped by a check nobody answered, and the run stays open, like any journey the person has yet to finish. The step passes whichever way the decision went, because getting the journey a decision is its whole job. It publishes action, the decision that stood, with the heading, wording and reference your answer carried or the heading and wording of the fallback that stood in for it, and the redirect_url on a redirect.

​
When the fault is ours

The fallback is yours to decide what happens when your system cannot answer. It never decides a check that could not be asked because of how it is registered or how we asked it, since that is no answer of yours and no outage of yours either. These are faults on our side:
  • Your endpoint refuses the request, answering 400, 401, 403, 404, 405, 410, 415 or 422. It answered, and said the request we made cannot be served, which is a proof, a URL or a request that needs putting right.
  • Your auth service refuses the credentials registered for it.
  • The workflow registers no checks endpoint, or the check fails on our side before it reaches you.
None of them takes the fallback, so none ends the run, carries it on, or shows the person your wording. The step reads as an error carrying the reason gate-check-faulted, and the person is shown the step’s own title and content with our message, which asks them to try again later. Nothing after the step is part of their journey, and the run stays open, neither gated nor using a credit. Each try asks the check again, so once the fault is put right the next try settles it. A person held because your system did not answer a hold reads the reason vendor-unavailable instead, which is how a screen tells the two apart. A workflow whose latest version declares a gate check it cannot ask starts nothing: one that registers no checks endpoint, or whose check falls back to a redirect whose link is not on the workflow’s list of places a person may be sent. Creating a verification on it, or resetting one onto it, is refused with 500 and the code workflow-misconfigured, so the fault is found before anybody reaches the gate.

​
Review

review The last step of every hosted workflow. The user reads back what they provided and confirms, and that confirmation is the submission - it cannot be given while any step is unfinished. The wording of the screen is the workflow’s own. A staged workflow has no review step: the run of the checks submits it. The step is also where the user declares things for themselves - that they accept your terms, that what they provided is true. Each declaration is its own tick box, worded in Markdown so it can link out to the terms or the policy it refers to, under a heading of its own where it needs one. One you have not marked optional has to be ticked before the submission is accepted; an optional one records whichever way it was left, and may be presented already ticked. A declaration you require cannot be: accepting it is the person’s own act. The answer records every declaration with the wording it was ticked against, so a record says what was agreed to on the day rather than what the workflow says now.