> ## Documentation Index > Fetch the complete documentation index at: https://docs.privue.ai/llms.txt > Use this file to discover all available pages before exploring further. # Read a workflow > Read the journey a workflow key runs, step by step. Read this to see how the workflow is conducted, what it asks for, and how each step is answered over the API: the slots its documents go in and the values it takes, under `intake`. The mode, the step keys and each step's intake are stable: they are how you address a document or a value, so they do not change under a workflow you are integrated against. Everything else here is configuration we hold and maintain - the settings on a step, the conditions that gate it, which steps exist at all - and those are ours to tune as a journey is refined. A refined journey is published as the workflow's next version, and this reads the latest version, which is the one a verification created now runs. A verification already created keeps the version it names in `version` until it is reset, so a refinement never changes what one under way asks for or how a finished one reads. So build against the mode, the keys and the intake, and read the rest. For results, drive off the `steps` array a verification returns, where every entry carries the same envelope whatever the workflow does. Every step the workflow can present is returned, in the order they are answered. A step that carries a condition is only presented when that condition holds, so any one verification walks some of these rather than all of them. Which steps a given verification actually walked is on its record, which reports those and leaves the rest out. ## OpenAPI ````yaml /verification/api-reference/openapi.json get /workflows/{workflow_key} openapi: 3.1.0 info: title: Verify with Privue description: >- Start identity-and-business verifications and read the results. There are three ways to run one, and a verification reads the same whichever it was. Every workflow declares which it is for as its `mode`, and a workflow is one of them and never more. **Hosted.** You create a verification with the user's mobile number and receive a journey URL to hand to them. They work through the steps your workflow configures, on our screens, and submit. Use this when the person being verified is reachable and holds their own documents. **Staged.** You create a verification, upload each document you hold against the step it answers, and ask for the checks to run. They take longer than a request should be held open, so you read the result from a callback or by polling. Use this when documents reach you over time, or when you want them kept on the record to download later. **Instant.** You send the whole submission in one request. The checks run before it answers, so the reply is the finished record. The documents are read as they arrive and stored nowhere. Use this when you hold everything already and want the answer in the call you made. Whichever it was, you read the whole record: every step, its state, what it collected, and why anything did not pass. An instant verification hands you that record in its reply; for the other two, poll the verification or register a callback endpoint and be told when it is submitted. Across your whole account you can list the workflows configured for you, count your verifications by status, and page through the records behind a count. Every error response has the shape `{"code": "...", "detail": "..."}`. Branch on `code`: several causes share a status, and `detail` is written for a person reading a log rather than for code. Treat a code you do not recognise as the status it arrived at. version: 0.1.0 servers: - url: https://api.verify.privue.ai description: Production security: [] tags: - name: Workflows description: >- The workflows configured for your account. Read one to see its mode, the documents it asks for, and how each step is answered over the API: the slots its documents go in and the values it takes. - name: Verifications description: >- Starting a verification, ending one, clearing one to run the same subject again, and purging one. Shared by both modes. A start answers 201 when it created the verification and 200 when the subject already had one, so a duplicate is visible from the status code alone. - name: Hosted workflows description: >- For a workflow the person being verified walks themselves. Start a verification with their mobile number, hand them the journey URL on the record, or open it for them from inside your own app with a handoff. - name: Staged workflows description: >- For a workflow you build up from documents you already hold. Upload each file against the step and slot it answers, withdraw one you got wrong, then ask for the checks to run and read the result when they have. Nobody is sent anywhere. - name: Instant workflows description: >- For a workflow answered in the request that asks it. Send the whole submission at once and read the finished record in the reply. Nothing is kept of the documents and nothing is left open to come back to. - name: Results description: >- Reading what a verification came to: one record, a page of them, counts across your account, and links to the files it holds. paths: /workflows/{workflow_key}: get: tags: - Workflows summary: Read a workflow description: >- Read the journey a workflow key runs, step by step. Read this to see how the workflow is conducted, what it asks for, and how each step is answered over the API: the slots its documents go in and the values it takes, under `intake`. The mode, the step keys and each step's intake are stable: they are how you address a document or a value, so they do not change under a workflow you are integrated against. Everything else here is configuration we hold and maintain - the settings on a step, the conditions that gate it, which steps exist at all - and those are ours to tune as a journey is refined. A refined journey is published as the workflow's next version, and this reads the latest version, which is the one a verification created now runs. A verification already created keeps the version it names in `version` until it is reset, so a refinement never changes what one under way asks for or how a finished one reads. So build against the mode, the keys and the intake, and read the rest. For results, drive off the `steps` array a verification returns, where every entry carries the same envelope whatever the workflow does. Every step the workflow can present is returned, in the order they are answered. A step that carries a condition is only presented when that condition holds, so any one verification walks some of these rather than all of them. Which steps a given verification actually walked is on its record, which reports those and leaves the rest out. operationId: read_workflow_workflows__workflow_key__get parameters: - name: workflow_key in: path required: true schema: type: string title: Workflow Key responses: '200': description: 'The workflow: who completes it, and every step it can present.' content: application/json: schema: $ref: '#/components/schemas/WorkflowRecord' example: key: merchant-onboarding name: Merchant onboarding mode: hosted version: 3 expires_after_days: 30 groups: - key: registration title: Registration details content: The registrations the business is held under. steps: - key: contact type: form title: Before we start label: contact_email group: null required: true intake: slots: [] values: - email condition: null inputs: {} settings: fields: - key: email name: email content: Email address type: text optional: false carried: false choices: null pattern: email asked_when: [] note: null reads: [] - key: gst type: gst-certificate title: GST certificate label: tax_registration group: registration required: true intake: slots: - key: gst-certificate required: true kinds: - key: gst-certificate label: gst_certificate accept: - types: - pdf max: 1 min: 1 - types: - image max: 3 min: 3 values: [] condition: null inputs: {} settings: contact_details: false ask_if_registered: false certificate: title: null content: null label: gst_certificate - key: pan type: pan-card title: PAN card label: entity_pan group: registration required: true intake: slots: - key: pan-card required: true kinds: - key: pan-card label: entity_pan accept: - types: - image - pdf max: 1 min: 1 values: [] condition: op: in value: - Private Limited Company - Public Limited Company kind: step-comparison step_key: gst field: business_constitution inputs: gstin: step_key: gst field: gstin settings: card: title: null content: null label: entity_pan - key: identity type: digilocker title: Identity label: null group: null required: false intake: slots: [] values: [] condition: null inputs: {} settings: documents: - doc_type: aadhaar required: true - key: selfie type: selfie title: Selfie label: null group: null required: false intake: slots: - key: selfie required: true kinds: - key: selfie label: null accept: - types: - image max: 1 min: 1 values: [] condition: null inputs: {} settings: liveness: true face_match: false selfie: title: null content: null label: null - key: bank type: bank-account title: Bank account label: payout_account group: null required: true intake: slots: - key: bank-account-proof required: true kinds: - key: statement label: bank_statement accept: - types: - pdf max: 1 min: 1 - types: - image max: 6 min: 1 - key: cheque label: cancelled_cheque accept: - types: - image - pdf max: 1 min: 1 values: - account_number - ifsc condition: null inputs: names: step_key: pan field: names settings: mode: penny-less proof: title: null content: null documents: - kind: statement label: bank_statement title: null content: null - kind: cheque label: cancelled_cheque title: null content: null - key: trade-licence type: documents title: Trade licence label: null group: null required: false intake: slots: - key: licence required: true kinds: - key: licence label: trade_licence accept: - types: - pdf max: 1 min: 1 - types: - image max: 3 min: 3 - key: lease required: false kinds: - key: lease label: lease_agreement accept: - types: - pdf max: 1 min: 1 values: [] condition: null inputs: {} settings: slots: - key: licence title: Shop and establishment licence content: null required: true kinds: - key: licence label: trade_licence title: null content: null accept: - types: - pdf max: 1 min: 1 - types: - image max: 3 min: 3 - key: lease title: Lease agreement content: null required: false kinds: - key: lease label: lease_agreement title: null content: null accept: - types: - pdf max: 1 min: 1 - key: premises type: premises-photos title: Premises photos label: null group: null required: false intake: slots: [] values: [] condition: null inputs: {} settings: photos: - key: storefront label: storefront_photo title: The front of the premises content: null min_count: 1 - key: interior label: interior_photo title: Inside the premises content: null min_count: 1 - key: premises-proof type: address-proof title: Proof of premises label: null group: null required: false intake: slots: - key: utility-bill required: true kinds: - key: electricity label: electricity_bill accept: - types: - image - pdf max: 1 min: 1 values: [] condition: null inputs: addresses: step_key: gst field: addresses names: step_key: gst field: names settings: slots: - key: utility-bill title: Utility bill content: null required: true kinds: - key: electricity label: electricity_bill title: null content: null accept: - types: - image - pdf max: 1 min: 1 min_verified_addresses: 1 - key: alt-business-proof type: documents title: Alternative proof of business label: null group: null required: true intake: slots: - key: incorporation required: true kinds: - key: incorporation label: incorporation_certificate accept: - types: - image - pdf max: 1 min: 1 values: [] condition: kind: step-outcome step_key: gst settled: failed inputs: {} settings: slots: - key: incorporation title: Certificate of incorporation content: null required: true kinds: - key: incorporation label: incorporation_certificate title: null content: null accept: - types: - image - pdf max: 1 min: 1 - key: addresses type: address-tagging title: Tag the addresses label: null group: null required: false intake: slots: [] values: - addresses condition: null inputs: presented_addresses: step_key: premises field: addresses known_addresses: step_key: gst field: addresses settings: tags: - Registered Office - Principal Business Address - Additional Place of Business - key: review type: review title: Review label: applicant_signoff group: null required: true intake: slots: [] values: [] condition: null inputs: {} settings: declarations: - key: terms-of-service label: tos_consent title: Terms of service content: >- I accept the [terms of service](https://yourapp.com/terms) and the [privacy policy](https://yourapp.com/privacy). optional: false default: false - key: information-true label: truth_declaration title: null content: >- Everything I have provided is true and correct to the best of my knowledge. optional: false default: false - key: contact-on-whatsapp label: whatsapp_optin title: null content: >- You may contact me about this application on WhatsApp. optional: true default: false submit_label: Submit success_title: Submitted success_message: >- Thank you for providing all the information. We will be in touch. environment: production credits: granted: 700 consumed: 412 expired: 0 revoked: 0 remaining: 288 expiring: - amount: 88 'on': '2026-09-30' - amount: 200 'on': '2027-03-31' runs: live: 17 limit: 25 resets: granted: 50 drawn: 6 expired: 0 revoked: 0 remaining: 44 expiring: - amount: 24 'on': '2027-03-31' - amount: 20 'on': '2027-06-30' output_transformations: gst-certificate: legal_name: name: company_name transform: null registration_date: name: null transform: kind: jsonata expression: $fromMillis($toMillis($), '[D01]/[M01]/[Y0001]') primary_business_address: name: registered_address transform: kind: jsonata expression: >- street & ', ' & city & ', ' & state & ' ' & postal_code filings[].filing_date: name: null transform: kind: jsonata expression: $fromMillis($toMillis($), '[D01]/[M01]/[Y0001]') pan-card: pan: name: pan_number transform: null aadhaar_seeded: name: null transform: kind: jsonata expression: '$ ? ''Y'' : ''N''' output_names: gst-certificate: legal_name: company_name primary_business_address: registered_address pan-card: pan: pan_number '400': description: |- No active workflow is configured under that key for your account. The code is `workflow-not-found`. content: application/json: example: code: workflow-not-found detail: client 'acme' has no active workflow 'merchant-onboarding' schema: $ref: '#/components/schemas/ErrorResponse' '401': description: |- The API key is missing, malformed, or revoked. The code is `unauthenticated`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: unauthenticated detail: Missing or malformed Authorization header '403': description: >- The workflow belongs to the other environment. An API key is for `uat` or for `production` and reaches only that environment's workflows. Or the key is valid but not enrolled for verifications, or not set up for exactly one of `uat` and `production`, in which case ask us to reissue it. The code is one of `environment-mismatch` or `client-not-enrolled`. content: application/json: example: code: environment-mismatch detail: >- workflow 'merchant-onboarding' is production and this request is for uat schema: $ref: '#/components/schemas/ErrorResponse' '422': description: |- An identifier in the path is not in the shape it takes. The code is `request-invalid`. content: application/json: example: code: request-invalid detail: >- verification_id: Input should be a valid UUID, invalid character: found `n` at 1 schema: $ref: '#/components/schemas/ErrorResponse' '429': description: |- The API key is rate limited. Retry after a pause. The code is `rate-limited`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: rate-limited detail: 'Unauthorized: RATE_LIMITED' '503': description: |- API keys could not be checked right now. Retry. The code is `auth-unavailable`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: auth-unavailable detail: Auth provider unavailable security: - HTTPBearer: [] components: schemas: WorkflowRecord: properties: key: type: string title: Key description: The key you name when creating a verification on this workflow. name: type: string title: Name description: The workflow's name, for showing in your own tools. mode: $ref: '#/components/schemas/WorkflowMode' description: >- How verifications on this workflow are conducted. `hosted`: the person being verified walks the journey on our screens and submits it. `staged`: you create a verification, upload each document against the step it answers, and then ask for the checks to run. `instant`: you send the whole submission in one request, which runs the checks and answers with the finished record. A workflow is one of the three, and every endpoint belonging to another is refused on it. version: type: integer minimum: 1 title: Version description: >- The workflow's latest version, which is the one a verification created now runs. Versions are numbered from 1, and every change to the journey is published as the next one, so a number names one journey for good. A verification keeps the version it was created on until it is reset, so a change reaches the verifications created after it and never one already under way. The mode is the workflow's, and the same on every version. expires_after_days: type: integer title: Expires After Days description: >- How long a verification on the version reported here holds a user's data, counted from their last action. Once that window runs out the verification expires and everything the user provided is deleted. A verification is held for as long as the version it runs says. groups: items: $ref: '#/components/schemas/StepGroup' type: array title: Groups description: >- The named parts the version reported here presents its steps in, in the order a user meets them. A step that belongs to one names it in `group`, and the steps of a group are consecutive, so each group heads one unbroken run of `steps`. A version that presents its steps under no headings at all has none of these. steps: items: $ref: '#/components/schemas/WorkflowStepRecord' type: array title: Steps description: >- Every step the version reported here can present, in the order a user meets them. A step that carries a condition is only presented when that condition holds, so any one verification walks some of these rather than all of them. environment: $ref: '#/components/schemas/Environment' description: >- Which environment this workflow is in: `uat` for the ones you integrate and test against, `production` for your real work. An API key belongs to one environment and reaches only that environment's workflows, so a key of the other one is refused with `403`. A uat workflow's key ends in `-uat` and a production workflow's never does, so the key in your own configuration says which you are pointed at. A run is identical in both: the same steps, the same checks, the same verdicts and the same credits. credits: $ref: '#/components/schemas/WorkflowCredits' description: This workflow's prepaid credits as they stand. runs: $ref: '#/components/schemas/WorkflowRuns' description: >- How many verifications this workflow has going, against how many it may. An instant workflow reports these too: its verifications are open while their checks run, so they count towards the ceiling for as long as they take to answer. resets: $ref: '#/components/schemas/WorkflowResets' description: >- The resets this workflow was sold, where they went, and what is left. They are sold with credits on the same terms and expire with them, so this reads exactly as `credits` does. Clearing a verification that had not ended draws one, because the run being cleared was never charged for. It is held by the workflow rather than by any one verification, so where the allowance goes is a question about the workflow and not about the record a reset happened to fall on. A verification's own `resets` counts every reset of it, drawn or not. An instant workflow reports these unmoved: its verifications are answered in the request that made them, so they are asked again rather than reset and nothing on one ever draws. output_transformations: additionalProperties: additionalProperties: $ref: '#/components/schemas/OutputTransformation' type: object propertyNames: $ref: '#/components/schemas/StepType' type: object title: Output Transformations description: >- How the outputs of the version reported here reach you, by step type. Each entry names a field of what that step type publishes by the path it sits at, and states the `name` it arrives under in `collected.outputs`, the `transform` that converts its value, or both; `[]` in a path descends into every record of a list. A step type with no entry here reaches you as this reference describes it, as does every step type when this is empty. A `transform` is a JSONata expression over the one value at its path, in the shape this reference documents it, and what it yields arrives in that value's place. It reads nothing else, so it never reaches another field or another step, and it always yields a value. Where a version's transformation cannot be applied to a verification's value, reading that verification answers `workflow-misconfigured`. Only `collected.outputs` is transformed. The paths on the left are the names used everywhere else a field is named, this reference and `collected.answer` included, so read this to translate between the two. The map belongs to the version, so a verification's outputs reach you as the version it runs states, and a change to it reaches the verifications created after it. output_names: additionalProperties: additionalProperties: type: string type: object propertyNames: $ref: '#/components/schemas/StepType' type: object title: Output Names description: >- The names alone from `output_transformations`, by step type: each published path mapped to the `name` it arrives under in `collected.outputs`, for every entry that states one. A path whose entry states only a `transform` keeps its own name and is not listed. A name is not the whole of how a field reaches you where its entry also converts the value, so read `output_transformations` for that. type: object required: - key - name - mode - version - expires_after_days - groups - steps - environment - credits - runs - resets - output_transformations - output_names title: WorkflowRecord description: >- A workflow as it is configured for you: who completes it, and the journey its key runs, step by step. Everything the journey declares is the latest version's, which is the one a verification created now runs. A verification created earlier runs the version it names in `version`, and reads under that version for as long as it lasts. The mode, the step keys and each step's intake are stable. The rest is configuration we maintain and tune without notice, so read it to understand a journey rather than to build behaviour against; the stable thing to integrate with is the verification record. ErrorResponse: properties: code: $ref: '#/components/schemas/ErrorCode' description: >- What went wrong. Branch on this rather than on the status code, which several causes share, and never on `detail`. Treat a code you do not recognise as the status it arrived at: codes are added as new causes become reachable, and an existing one never changes meaning. detail: type: string title: Detail description: >- What went wrong, in words, naming the workflow, verification, step or field at fault where one is. Written for a person reading a log rather than for code to read, so it is not stable and nothing should be matched against it. type: object required: - code - detail title: ErrorResponse description: The envelope every failure is answered in. WorkflowMode: type: string enum: - hosted - staged - instant title: WorkflowMode description: >- How a verification on this workflow is conducted, which every other rule about it follows from. StepGroup: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key description: >- Identifies the group. Each step presented under it names this key in its `group`. title: type: string minLength: 1 title: Title description: The heading the group's steps are presented under. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content description: The wording shown under that heading, where there is any. additionalProperties: false type: object required: - key - title title: StepGroup description: >- A named part of the journey, presented as one heading over the steps that name it. WorkflowStepRecord: properties: key: type: string title: Key description: >- Identifies the step. The same key names this step on every verification. type: $ref: '#/components/schemas/StepType' description: >- Which of the step types this is. [Step types](/verification/step-types) lists them. title: type: string title: Title description: >- The heading this step is presented under, in your workflow's own words. label: anyOf: - type: string - type: 'null' title: Label description: >- Your own name for this step, where your workflow carries one. Several steps may share one, so a journey that asks a sole proprietor, a partner and a director each for a PAN reads the same name on whichever of them ran. Null where the workflow carries none; the `key` is what names this step everywhere. group: anyOf: - type: string - type: 'null' title: Group description: >- The part of the journey this step is presented under, naming one of the workflow's `groups`. Null on a step that stands outside every group. required: type: boolean title: Required description: >- Whether the step has to be completed, or may be declined or left out. intake: $ref: '#/components/schemas/StepIntakeRecord' description: >- How the step is answered over this API: which slots its documents go in, and which values it takes. On a workflow you supply yourself this is exactly what you send for the step. Both are empty on a step answered from what earlier steps established, and on one the person being verified answers on their own screens, which only a hosted workflow declares. condition: anyOf: - oneOf: - $ref: '#/components/schemas/ContextComparison' - $ref: '#/components/schemas/ContextSupplied' - $ref: '#/components/schemas/ContextMissing' - $ref: '#/components/schemas/StepComparison' - $ref: '#/components/schemas/StepOutcome' - $ref: '#/components/schemas/StepPublished' - $ref: '#/components/schemas/StepNotPublished' - $ref: '#/components/schemas/AllOf' - $ref: '#/components/schemas/AnyOf' discriminator: propertyName: kind mapping: all: '#/components/schemas/AllOf' any: '#/components/schemas/AnyOf' context-comparison: '#/components/schemas/ContextComparison' context-missing: '#/components/schemas/ContextMissing' context-supplied: '#/components/schemas/ContextSupplied' step-comparison: '#/components/schemas/StepComparison' step-not-published: '#/components/schemas/StepNotPublished' step-outcome: '#/components/schemas/StepOutcome' step-published: '#/components/schemas/StepPublished' - type: 'null' title: Condition description: >- What has to hold for this step to be presented at all. Null on a step every user meets. A step whose condition does not hold is left out of the record, and reads `not-applicable` on one read with `include_not_applicable`. inputs: additionalProperties: anyOf: - $ref: '#/components/schemas/ContextValue' - $ref: '#/components/schemas/StepValue' - $ref: '#/components/schemas/LiteralValue' - $ref: '#/components/schemas/FirstValue' type: object title: Inputs description: >- The values this step is given before it runs, each naming what it is read from: a value an earlier step published, a field of the context you supplied when creating it, a fixed value, or the first of several such sources that has a value. settings: anyOf: - $ref: '#/components/schemas/FormSettings' - $ref: '#/components/schemas/DocumentsSettings' - $ref: '#/components/schemas/ParsedDocumentsSettings' - $ref: '#/components/schemas/PanCardSettings' - $ref: '#/components/schemas/BankAccountSettings' - $ref: '#/components/schemas/GstCertificateSettings' - $ref: '#/components/schemas/DigilockerSettings' - $ref: '#/components/schemas/SelfieSettings' - $ref: '#/components/schemas/PremisesPhotosSettings' - $ref: '#/components/schemas/AddressTaggingSettings' - $ref: '#/components/schemas/AddressProofSettings' - $ref: '#/components/schemas/UdyamSettings' - $ref: '#/components/schemas/PcbCertificateSettings' - $ref: '#/components/schemas/NameMatchSettings' - $ref: '#/components/schemas/GateCheckSettings' - $ref: '#/components/schemas/ReviewSettings' title: Settings description: >- How this step is configured, in the shape its type takes. What it asks for is worded here; `intake` names the same slots and kinds as the keys you address a document by. type: object required: - key - type - title - label - group - required - intake - settings title: WorkflowStepRecord description: >- One step of a workflow as it is configured, whether or not a given user is asked for it. The keys and the intake are stable: they are how a document or a value is addressed. The settings and the condition are a reference view of configuration that changes without notice as a journey is tuned. Environment: type: string enum: - uat - production title: Environment description: >- Which environment an API key, and the workflows it can reach, belong to. Nothing about a run differs between them: the same steps, the same sources, the same verdicts, the same credits. What differs is what the client treats a run as, so the two are held apart by refusing a key every workflow but its own. WorkflowCredits: properties: granted: type: integer title: Granted description: >- Credits granted to this workflow in total, every top-up included. Nothing takes away from it: where the credits went afterwards is what the figures below say, so this only ever rises. consumed: type: integer title: Consumed description: >- Credits this workflow's runs have used. One run uses one credit, whatever the workflow asks for and however many of its checks ran. A run one of your own checks stopped uses none: it is counted as gated instead. expired: type: integer title: Expired description: >- Credits that ran out of time. Credits are granted on a term, and whatever is still standing on a term once its last day has passed is forfeited. They stop counting the day the term goes, so this figure and `remaining` both move on that date whether or not anything was run. This is the one thing that moves `remaining` without a verification behind it, so it is what explains a balance that fell while nothing was running. revoked: type: integer title: Revoked description: >- Credits taken back off this workflow, which is a correction we make and tell you about. Zero unless we have made one. remaining: type: integer title: Remaining description: >- Credits left to spend. Once this reaches zero, creating a verification on this workflow is refused with `402` and the verifications already on it accept no further documents, answers or runs until it is topped up. They stay readable. It reads negative when verifications that had already started when the balance ran out go on to end, each using the credit it owes. No more than `runs.limit` verifications can be in that position, so that is as far below zero as this goes. expiring: items: $ref: '#/components/schemas/WorkflowCreditExpiry' type: array title: Expiring description: >- What this workflow's remaining credits are standing on, soonest to expire first. Every credit is granted on a term and each grant carries its own, so a balance is spread over as many terms as it took to build up, and wherever there is anything left to spend these figures add up to `remaining`. Spending draws on the term that comes up soonest, so this is also the order the credits will be used in, and the first entry is the one to watch: its `on` is the next date this workflow loses credits on, and its `amount` is how many it loses. Empty when there is nothing left to spend, however the credits went, on a workflow that has never been granted any, and while `remaining` is negative: a debt stands on no term and expires on no date. type: object required: - granted - consumed - expired - revoked - remaining - expiring title: WorkflowCredits description: >- A workflow's prepaid credits: what it was granted, where that went, and what is left. The three figures that take credits away account for the whole of the difference, so `granted` less `consumed`, `expired` and `revoked` is always `remaining`. WorkflowRuns: properties: live: type: integer title: Live description: >- Verifications on this workflow that have not ended: every one whose status is `open` or `submitted`. One that has completed, been cancelled, been gated, failed or expired is not counted. limit: type: integer title: Limit description: >- How many verifications this workflow may have going at once. A verification that has not ended has used no credit, so this is a separate limit from the balance: it caps the work you can have in flight, where credits cap the work that can finish. Creating a verification while `live` has reached this figure is refused with `409`. Finishing or cancelling one frees a place immediately. Ask us if you need more room. type: object required: - live - limit title: WorkflowRuns description: >- How many of a workflow's verifications are still going, against how many it may have at once. WorkflowResets: properties: granted: type: integer title: Granted description: >- Resets sold to this workflow in total, every sale included. Nothing takes away from it: where they went afterwards is what the figures below say, so this only ever rises. drawn: type: integer title: Drawn description: >- Resets this workflow's verifications have drawn between them. One reset of a verification that had not ended draws one, whichever of the workflow's verifications it was. expired: type: integer title: Expired description: >- Resets that ran out of time. They are sold on the same term as the credits they came with, so whatever is still standing on a term once its last day has passed is forfeited with them. revoked: type: integer title: Revoked description: Resets taken back, which only we do and only to put something right. remaining: type: integer title: Remaining description: >- Resets left to draw on. At zero, clearing an `open` or `submitted` verification is refused with `402` until the workflow is topped up, on any of its verifications. Clearing a `completed`, `cancelled` or `failed` one goes on working, drawing nothing. Buying more is what fills this, as it is for credits, and resets may be bought on their own where runs are not what you are short of. expiring: items: $ref: '#/components/schemas/WorkflowResetExpiry' type: array title: Expiring description: >- What the remaining resets are standing on, soonest to expire first. Adds up to `remaining` wherever there is anything left, and empty when there is not. type: object required: - granted - drawn - expired - revoked - remaining - expiring title: WorkflowResets description: >- A workflow's resets: what it was sold, where they went, and what is left. Resets are sold with credits, on the same terms, and are read exactly as the credits beside them. Clearing a verification that is still `open` or `submitted` draws one, because the run you are clearing was never charged for and the checks are run again at our cost. Clearing a `completed` or `cancelled` one draws nothing, that run having been charged and the one it opens being charged in turn, and neither does clearing a `failed` one, which is a run we could not carry through. The three figures that take resets away account for the whole of the difference, so `granted` less `drawn`, `expired` and `revoked` is always `remaining`. OutputTransformation: properties: name: anyOf: - type: string - type: 'null' title: Name description: >- The key this field arrives under in `collected.outputs`. Null where it keeps its own. transform: anyOf: - $ref: '#/components/schemas/JsonataTransform' - type: 'null' description: >- How this field's value is converted on its way to you. Null where it arrives as published. additionalProperties: false type: object title: OutputTransformation description: >- How one published field reaches you: under which name, and in which shape. ErrorCode: type: string enum: - unauthenticated - client-not-enrolled - rate-limited - auth-unavailable - environment-mismatch - request-invalid - body-unreadable - page-cursor-invalid - window-invalid - request-too-large - not-found - method-not-allowed - internal-error - workflow-not-found - workflow-version-not-found - workflow-not-runnable - workflow-not-walkable - workflow-misconfigured - context-incomplete - context-value-invalid - mobile-required - journey-fields-refused - return-url-not-allowed - reference-taken - verification-not-found - verification-not-open - verification-expired - run-in-progress - credits-exhausted - resets-exhausted - live-limit-reached - step-not-found - step-not-ready - step-invalid - document-not-found - document-not-stored - document-too-large - document-type-not-allowed title: ErrorCode description: >- What went wrong, as a value to branch on. Published vocabulary, stated here rather than shared with any other product of ours: these are read by integrations we do not control, so a name here means what it says for as long as the endpoint answering it exists. One code names one cause, so a status carrying several causes is told apart by the code and never by the message. Codes are added as new causes become reachable; an integration therefore treats an unrecognised code as the status it arrived at. StepType: type: string enum: - form - documents - parsed-documents - pan-card - bank-account - gst-certificate - digilocker - selfie - premises-photos - address-tagging - address-proof - udyam - pcb-certificate - name-match - gate-check - review title: StepType description: The sixteen step types. This list is closed. StepIntakeRecord: properties: slots: items: $ref: '#/components/schemas/SlotRecord' type: array title: Slots description: >- The named slots this step's documents are uploaded to, each saying whether it is required and which kinds of document satisfy it, every kind saying how many files it arrives as and in what formats. Empty on a step that takes no documents over this API. values: items: type: string type: array title: Values description: >- The names of the values this step takes in a run request. Empty on a step answered by its documents alone, or from what earlier steps established. type: object required: - slots - values title: StepIntakeRecord description: >- How a step is answered over this API: the slots its documents go in, and the values it takes. ContextComparison: properties: op: $ref: '#/components/schemas/Operator' description: How the two sides are compared. value: title: Value description: >- The value compared against, a list of them when the operator is `in` or `not-in`. kind: type: string const: context-comparison title: Kind description: Identifies this form of condition. default: context-comparison field: type: string minLength: 1 title: Field description: The context field this reads, by the name you supplied it under. additionalProperties: false type: object required: - op - value - field title: ContextComparison description: Compare a fact the client supplied at start against a fixed value. ContextSupplied: properties: kind: type: string const: context-supplied title: Kind description: Identifies this form of condition. default: context-supplied field: type: string minLength: 1 title: Field description: The context field this reads, by the name you supplied it under. additionalProperties: false type: object required: - field title: ContextSupplied description: True when the client supplied this context field at start. ContextMissing: properties: kind: type: string const: context-missing title: Kind description: Identifies this form of condition. default: context-missing field: type: string minLength: 1 title: Field description: The context field this reads, by the name you supplied it under. additionalProperties: false type: object required: - field title: ContextMissing description: True when the client supplied no such context field. StepComparison: properties: op: $ref: '#/components/schemas/Operator' description: How the two sides are compared. value: title: Value description: >- The value compared against, a list of them when the operator is `in` or `not-in`. kind: type: string const: step-comparison title: Kind description: Identifies this form of condition. default: step-comparison step_key: type: string minLength: 1 title: Step Key description: The step this reads, named by its key. field: type: string minLength: 1 title: Field description: The field of that step's published outputs this reads. additionalProperties: false type: object required: - op - value - step_key - field title: StepComparison description: Compare a value another step published against a fixed value. StepOutcome: properties: kind: type: string const: step-outcome title: Kind description: Identifies this form of condition. default: step-outcome step_key: type: string minLength: 1 title: Step Key description: The step this reads, named by its key. settled: $ref: '#/components/schemas/OutcomeKind' description: The outcome the step must have settled on. additionalProperties: false type: object required: - step_key - settled title: StepOutcome description: True when the named step has settled the way this says. StepPublished: properties: kind: type: string const: step-published title: Kind description: Identifies this form of condition. default: step-published step_key: type: string minLength: 1 title: Step Key description: The step this reads, named by its key. field: type: string minLength: 1 title: Field description: The field of that step's published outputs this reads. additionalProperties: false type: object required: - step_key - field title: StepPublished description: >- True when the named step has passed and published a value for this field. StepNotPublished: properties: kind: type: string const: step-not-published title: Kind description: Identifies this form of condition. default: step-not-published step_key: type: string minLength: 1 title: Step Key description: The step this reads, named by its key. field: type: string minLength: 1 title: Field description: The field of that step's published outputs this reads. additionalProperties: false type: object required: - step_key - field title: StepNotPublished description: >- True when the named step has passed and published no value for this field. AllOf: properties: kind: type: string const: all title: Kind description: Identifies this form of condition. default: all conditions: items: oneOf: - $ref: '#/components/schemas/ContextComparison' - $ref: '#/components/schemas/ContextSupplied' - $ref: '#/components/schemas/ContextMissing' - $ref: '#/components/schemas/StepComparison' - $ref: '#/components/schemas/StepOutcome' - $ref: '#/components/schemas/StepPublished' - $ref: '#/components/schemas/StepNotPublished' - $ref: '#/components/schemas/AllOf' - $ref: '#/components/schemas/AnyOf' discriminator: propertyName: kind mapping: all: '#/components/schemas/AllOf' any: '#/components/schemas/AnyOf' context-comparison: '#/components/schemas/ContextComparison' context-missing: '#/components/schemas/ContextMissing' context-supplied: '#/components/schemas/ContextSupplied' step-comparison: '#/components/schemas/StepComparison' step-not-published: '#/components/schemas/StepNotPublished' step-outcome: '#/components/schemas/StepOutcome' step-published: '#/components/schemas/StepPublished' type: array minItems: 1 title: Conditions description: The conditions this combines. additionalProperties: false type: object required: - conditions title: AllOf description: True when every branch is true. AnyOf: properties: kind: type: string const: any title: Kind description: Identifies this form of condition. default: any conditions: items: oneOf: - $ref: '#/components/schemas/ContextComparison' - $ref: '#/components/schemas/ContextSupplied' - $ref: '#/components/schemas/ContextMissing' - $ref: '#/components/schemas/StepComparison' - $ref: '#/components/schemas/StepOutcome' - $ref: '#/components/schemas/StepPublished' - $ref: '#/components/schemas/StepNotPublished' - $ref: '#/components/schemas/AllOf' - $ref: '#/components/schemas/AnyOf' discriminator: propertyName: kind mapping: all: '#/components/schemas/AllOf' any: '#/components/schemas/AnyOf' context-comparison: '#/components/schemas/ContextComparison' context-missing: '#/components/schemas/ContextMissing' context-supplied: '#/components/schemas/ContextSupplied' step-comparison: '#/components/schemas/StepComparison' step-not-published: '#/components/schemas/StepNotPublished' step-outcome: '#/components/schemas/StepOutcome' step-published: '#/components/schemas/StepPublished' type: array minItems: 1 title: Conditions description: The conditions this combines. additionalProperties: false type: object required: - conditions title: AnyOf description: True when at least one branch is true. ContextValue: properties: context_key: type: string minLength: 1 title: Context Key description: >- The context field the value is read from, by the name you supplied it under. additionalProperties: false type: object required: - context_key title: ContextValue description: 'Plumb a fact the client supplied at start: {"context_key": ""}.' StepValue: properties: step_key: type: string minLength: 1 title: Step Key description: The step the value is read from, named by its key. field: type: string minLength: 1 title: Field description: The field of that step's published outputs the value is read from. additionalProperties: false type: object required: - step_key - field title: StepValue description: >- Plumb a value another step published: {"step_key": "", "field": ""}. LiteralValue: properties: value: title: Value description: The fixed value. additionalProperties: false type: object required: - value title: LiteralValue description: 'Plumb a fixed value the workflow author wrote down: {"value": ...}.' FirstValue: properties: first_of: items: anyOf: - $ref: '#/components/schemas/ContextValue' - $ref: '#/components/schemas/StepValue' - $ref: '#/components/schemas/LiteralValue' - $ref: '#/components/schemas/FirstValue' type: array minItems: 1 title: First Of description: >- The sources, read in order. The value is the earliest of them that has one. additionalProperties: false type: object required: - first_of title: FirstValue description: >- Plumb the first of several sources that carries a value: {"first_of": [, ...]}. The sources are read in order and the field takes the value of the earliest that has one, staying unset only when none does. This is how a field whose source depends on which branch of the journey ran gets its value: each source is a branch, and whichever one the user took is the one that carries it. FormSettings: properties: fields: items: $ref: '#/components/schemas/FormField' type: array title: Fields reads: items: $ref: '#/components/schemas/FormRead' type: array title: Reads additionalProperties: false type: object required: - fields title: FormSettings description: >- The declared fields of a form step, and the values it reads to decide which of them it asks. DocumentsSettings: properties: slots: items: $ref: '#/components/schemas/DocumentSlot' type: array minItems: 1 title: Slots additionalProperties: false type: object required: - slots title: DocumentsSettings description: The declared slots of a documents step. ParsedDocumentsSettings: properties: slots: items: $ref: '#/components/schemas/ReadableSlot' type: array minItems: 1 title: Slots description: The documents this step asks for. readings: items: $ref: '#/components/schemas/KindRules' type: array title: Readings description: The rules each kind is held to. additionalProperties: false type: object required: - slots title: ParsedDocumentsSettings description: The documents a step reads, and what each is held to. PanCardSettings: properties: card: $ref: '#/components/schemas/DocumentAsked' description: >- What this step asks for, in your own wording, and the name you know it by. Left out, it asks for a PAN card under its usual name. additionalProperties: false type: object title: PanCardSettings description: What this step's document is asked for as, and known by. BankAccountSettings: properties: mode: $ref: '#/components/schemas/BankVerificationMode' default: penny-less proof: $ref: '#/components/schemas/BankProofSettings' description: How the step asks for proof, and what it takes as proof. additionalProperties: false type: object title: BankAccountSettings description: >- Which Befisc verification the step runs, and how it asks for proof of the account. GstCertificateSettings: properties: contact_details: type: boolean title: Contact Details description: >- Whether 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. default: false ask_if_registered: type: boolean title: Ask If Registered description: >- Whether the user is asked if the business is GST registered before anything is uploaded. A business that is 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, since declining is how that answer is recorded. default: false certificate: $ref: '#/components/schemas/DocumentAsked' description: >- What this step asks for, in your own wording, and the name you know it by. Left out, it asks for a GST certificate under its usual name. additionalProperties: false type: object title: GstCertificateSettings description: >- What the step reads beyond the certificate, and what it asks before asking for one. DigilockerSettings: properties: documents: items: $ref: '#/components/schemas/ConsentedDocument' type: array minItems: 1 title: Documents additionalProperties: false type: object required: - documents title: DigilockerSettings description: >- Which government documents the DigiLocker consent asks for. Every listed document is requested in the consent. One the author marks optional may come back missing without failing the step: the step passes and reports the gap against it. SelfieSettings: properties: liveness: type: boolean title: Liveness default: true face_match: type: boolean title: Face Match default: false selfie: $ref: '#/components/schemas/DocumentAsked' description: >- What this step asks for, in your own wording, and the name you know it by. Left out, it asks for a selfie under its usual name. additionalProperties: false type: object title: SelfieSettings description: >- Which checks the selfie step runs; face match needs the identity_document input. PremisesPhotosSettings: properties: photos: items: $ref: '#/components/schemas/PhotoSlot' type: array minItems: 1 title: Photos additionalProperties: false type: object required: - photos title: PremisesPhotosSettings description: The photos asked for; every one carries a location by construction. AddressTaggingSettings: properties: tags: items: type: string type: array minItems: 1 title: Tags additionalProperties: false type: object required: - tags title: AddressTaggingSettings description: The tags a user picks from, one per address the step presents. AddressProofSettings: properties: slots: items: $ref: '#/components/schemas/DocumentSlot' type: array minItems: 1 title: Slots min_verified_addresses: type: integer minimum: -1 title: Min Verified Addresses additionalProperties: false type: object required: - slots - min_verified_addresses title: AddressProofSettings description: >- The documents an address proof asks for, and how many of the addresses they have to stand up. min_verified_addresses counts the addresses the documents must evidence between them: a positive number demands at least that many, and -1 demands every address the step was given. To collect documents without matching their addresses, ask for them with a documents step. UdyamSettings: properties: certificate: $ref: '#/components/schemas/DocumentAsked' description: >- What this step asks for, in your own wording, and the name you know it by. Left out, it asks for an Udyam certificate under its usual name. additionalProperties: false type: object title: UdyamSettings description: What this step's document is asked for as, and known by. PcbCertificateSettings: properties: band: $ref: '#/components/schemas/MatchBand' description: >- How close the holder's name has to come to one of the names on record. certificate: $ref: '#/components/schemas/DocumentAsked' description: >- What this step asks for, in your own wording, and the name you know it by. Left out, it asks for a PCB certificate under its usual name. additionalProperties: false type: object title: PcbCertificateSettings description: >- What the step asks for, and how close the name on it has to come to one of the names it is held to. NameMatchSettings: properties: checks: items: type: string type: array minItems: 1 title: Checks band: $ref: '#/components/schemas/MatchBand' description: How close a name has to come to the reference to count. additionalProperties: false type: object required: - checks title: NameMatchSettings description: >- The checks the step makes, and how close a name has to come to count. Each check is one input, plumbed from whichever step establishes that name. Names arriving on one input are alternatives rather than separate checks: a GST registration publishes its legal name and its trade name, and either one standing up has stood the registration up, so the closest of them is what the check comes to. GateCheckSettings: properties: check: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Check description: >- Names the question this step asks. It is sent with every request, so one endpoint answers every check a workflow asks and tells them apart by this name. reads: items: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ type: array title: Reads description: >- The values this check waits for, by the name each is plumbed in under. The step is part of the journey once every one of them has settled, whether or not it arrived. If any of them changes, the question is asked again when the person next reaches the step. A check that names none waits for nothing. The values decide when the question is asked, not what is sent: every request carries the whole verification record as it stands. redirect_label: anyOf: - type: string minLength: 1 - type: 'null' title: Redirect Label description: >- The wording on the link that sends the person on, whether your system answered `redirect` or the step fell back to one. A step that names none shows the link under the journey's own wording. when_unanswered: oneOf: - $ref: '#/components/schemas/CarryOnFallback' - $ref: '#/components/schemas/TerminateFallback' - $ref: '#/components/schemas/RedirectFallback' - $ref: '#/components/schemas/HoldFallback' title: When Unanswered description: >- What the step settles on when your endpoint could not be reached, or answered something that is not an answer, chosen by its `action`. `carry-on` lets the journey carry on, as an answer of `{"action": "carry-on"}` would. `terminate` ends it at this step, as `{"action": "terminate"}` would, which ends the run as `gated`. `redirect` ends it the same way and sends the person to its `redirect_url`, as `{"action": "redirect"}` would. Each of these records on the step that your system did not answer. `hold` settles on nothing: the person is held on the step, which reads as an error they can try again from, until your system answers. Every action but `carry-on` takes a `title` and `content`, shown to the person in place of the step's own. Where it ends the journey, that wording is fixed on the step when the check falls back, and published on it as the wording your system would otherwise have answered with. A request your endpoint refuses, answering a status such as `400`, `401`, `404` or `422`, or one your auth service refuses the registered credentials for, takes no fallback. Your system answered, and said the request cannot be served, which is a fault in how the check is registered or asked rather than a decision of yours. The person is held on the step, shown our own wording rather than this, until the check can be asked, and the step carries the reason `gate-check-faulted`. discriminator: propertyName: action mapping: carry-on: '#/components/schemas/CarryOnFallback' hold: '#/components/schemas/HoldFallback' redirect: '#/components/schemas/RedirectFallback' terminate: '#/components/schemas/TerminateFallback' additionalProperties: false type: object required: - check - when_unanswered title: GateCheckSettings description: >- Which question is put to your system, what it waits for, and what an unanswered check settles on. ReviewSettings: properties: declarations: items: $ref: '#/components/schemas/Declaration' type: array title: Declarations description: >- What the person states before submitting - that they accept your terms, that what they provided is true - each presented as its own tick box, in this order. The wording each one carried is recorded with the answer they gave it. submit_label: type: string minLength: 1 title: Submit Label default: Submit success_title: type: string minLength: 1 title: Success Title default: Submitted success_message: type: string minLength: 1 title: Success Message default: Thank you for providing all the information. We will be in touch. additionalProperties: false type: object title: ReviewSettings description: >- The final screen: what the person declares, the control that submits, and what they read after. WorkflowCreditExpiry: properties: amount: type: integer title: Amount description: >- Credits standing on this term. Always at least one; a term holding none is not reported. 'on': type: string format: date title: 'On' description: >- The last day these credits can be spent on, as `YYYY-MM-DD`. They are good for the whole of that day, and once it has passed they are gone: the workflow's `remaining` falls by this much and its `expired` rises by the same, with no verification having been run. type: object required: - amount - 'on' title: WorkflowCreditExpiry description: >- Credits standing on one term of a workflow's balance, and the last day they can be spent on. WorkflowResetExpiry: properties: amount: type: integer title: Amount description: >- Resets standing on this term. Always at least one; a term holding none is not reported. 'on': type: string format: date title: 'On' description: >- The last day these resets can be drawn on, as `YYYY-MM-DD`. They are good for the whole of that day, and once it has passed they are gone: the workflow's `remaining` falls by this much and its `expired` rises by the same, with no verification having been reset. type: object required: - amount - 'on' title: WorkflowResetExpiry description: >- Resets standing on one term of a workflow's allowance, and the last day they can be drawn on. JsonataTransform: properties: kind: type: string const: jsonata title: Kind description: The language the expression is written in. expression: type: string maxLength: 1000 minLength: 1 title: Expression description: >- A JSONata expression over the field's value, in the shape this reference documents it: `$` is that value, and what the expression yields arrives in its place. Under a path that descends with `[]` it runs once for each record. A null arrives as null, without the expression running. It reads that value and nothing else, so it never reaches another field of the step or another step. It always yields a value. Where it could find nothing, as a `$lookup` does for a value its table does not list and a filter does where no record matches, it states what arrives instead, written `... ?? ...`. additionalProperties: false type: object required: - kind - expression title: JsonataTransform description: >- A JSONata expression converting the value at one path into the shape it reaches you in. SlotRecord: properties: key: type: string title: Key description: Names this slot when a document is sent for it. required: type: boolean title: Required description: Whether the step needs this slot filled to be answered. kinds: items: $ref: '#/components/schemas/KindRecord' type: array title: Kinds description: The kinds of document that satisfy this slot; send one of them. type: object required: - key - required - kinds title: SlotRecord description: One slot of a step, as the client addresses and fills it. Operator: type: string enum: - eq - ne - in - not-in title: Operator description: Comparison operators over a referenced value. OutcomeKind: type: string enum: - passed - failed - declined - not-supplied title: OutcomeKind description: The settled outcomes a condition may reference. FormField: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key description: >- Identifies the field within the form. A gate follows this key, and a value plumbed in under it pre-fills the field for the person to confirm or correct. name: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ title: Name description: >- The name this field's value is published under, and the name the answer keys it by. Fields that can never both be asked may share one name, so that name carries whichever of them the journey reached. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content type: $ref: '#/components/schemas/FieldType' default: text optional: type: boolean title: Optional default: false carried: type: boolean title: Carried description: >- Publish the value plumbed into this field's key instead of asking the person for it. The field is never presented and never answered: it takes whatever the workflow plumbs in, under the gates it declares, and publishes it under its name. A field plumbed nothing publishes nothing, exactly as an optional field left blank does. This is how one name carries a value the person entered on the branch of the journey that asks for it, and a value the workflow already holds on the branch that does not. default: false choices: anyOf: - items: type: string type: array - type: 'null' title: Choices pattern: anyOf: - $ref: '#/components/schemas/NamedPattern' - type: 'null' asked_when: items: $ref: '#/components/schemas/AskedWhen' type: array title: Asked When description: >- Gates deciding whether this field is asked. Every one of them has to hold, so a field carrying none is always asked. A field the journey never asked publishes nothing, exactly as an optional field left blank does. note: anyOf: - type: string minLength: 1 - type: 'null' title: Note description: >- What the person is told about a value pre-filled into this field, in your own words - where it came from, or why it is already there. Shown only while the field still holds what was plumbed in, so it goes as soon as they change the value and never describes one they entered themselves. A field left to be pre-filled by a source that published nothing shows no note, so one journey reads it and another does not. additionalProperties: false type: object required: - key - name title: FormField description: One typed field of a form step. FormRead: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key description: >- Identifies the value within the form. Plumb a value in under this key for a gate to follow it. The value is never presented to the person being verified and never published in the step's outputs. type: $ref: '#/components/schemas/FieldType' description: The kind of value read, which fixes the shape it arrives in. default: text additionalProperties: false type: object required: - key title: FormRead description: >- A value the form is plumbed to decide what it asks, never shown and never published. DocumentSlot: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key description: Identifies the slot. Documents are uploaded against it. title: type: string minLength: 1 title: Title description: What the person filling it is asked for. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content description: >- Markdown telling them what counts, rendered under the title. Left out, the title stands alone. required: type: boolean title: Required description: Whether the step needs this slot filled to be answered. default: true kinds: items: $ref: '#/components/schemas/DocumentKind' type: array minItems: 1 title: Kinds description: >- The kinds of document that satisfy this slot, each saying what it is and how it arrives. A slot that takes one document names one kind, and every file in the slot is of the kind it was provided as. additionalProperties: false type: object required: - key - title - kinds title: DocumentSlot description: >- A named slot of a documents step, satisfied by the files of exactly one of its kinds. ReadableSlot: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key description: Identifies the slot. Documents are uploaded against it. title: type: string minLength: 1 title: Title description: What the person filling it is asked for, in your own wording. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content description: >- Markdown telling them what counts, under the title. Left out, the title stands alone. kinds: items: $ref: '#/components/schemas/ReadableDocument' type: array minItems: 1 title: Kinds description: >- The documents that satisfy this slot, any one of which does. Name more than one where either would do, and whoever provides the files says which they sent. required: type: boolean title: Required description: Whether the step needs this slot filled to be answered. default: true accept: items: $ref: '#/components/schemas/SlotAccept' type: array minItems: 1 title: Accept description: >- The intake shapes for this slot. The files in it must satisfy exactly one of them, and they count pages rather than documents: a slot accepting four files takes one document across up to four pages, read together in a single pass. additionalProperties: false type: object required: - key - title - kinds title: ReadableSlot description: >- One slot of a parsed-documents step: the documents it takes, and the files that make one up. A slot naming several kinds is satisfied by any one of them, which is how a requirement met by either of two documents is asked for once. Whoever sends the files names which kind they are, so the parser is still told what it is reading before a byte of it is read and nothing is guessed. A slot naming one kind fills that in itself. KindRules: properties: kind: $ref: '#/components/schemas/ReadableKind' description: The kind of document these rules are asked of. rules: items: oneOf: - $ref: '#/components/schemas/ValidRule' - $ref: '#/components/schemas/MatchesRule' - $ref: '#/components/schemas/EqualsRule' discriminator: propertyName: rule mapping: equals: '#/components/schemas/EqualsRule' matches: '#/components/schemas/MatchesRule' valid: '#/components/schemas/ValidRule' type: array minItems: 1 title: Rules description: What is asked of every document of it. additionalProperties: false type: object required: - kind - rules title: KindRules description: >- The rules every document of one kind is held to. Keyed by kind, so one entry serves every slot taking that kind however many a workflow declares, and a slot added later inherits them. DocumentAsked: properties: title: anyOf: - type: string minLength: 1 - type: 'null' title: Title description: What the user is asked to provide. Left out, its usual name. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content description: >- Markdown telling them what counts, under the title. Left out, the title stands alone. label: anyOf: - type: string minLength: 1 - type: 'null' title: Label description: >- This document's name in your own system, carried on every file provided for it. Give the same one to a document asked for on more than one branch of a journey and it reads the same whichever branch ran. additionalProperties: false type: object title: DocumentAsked description: >- What one document is asked for as, and the name it goes by in the client's own system. BankVerificationMode: type: string enum: - penny-drop - penny-less title: BankVerificationMode description: >- How an account is checked on the banking network. A penny drop credits one rupee to the account and reads back the name it is registered to, which confirms the account is live and can receive money. A penny-less check asks the network for that name without moving anything, and reaches fewer banks. BankProofSettings: properties: title: anyOf: - type: string minLength: 1 - type: 'null' title: Title description: >- What the user is asked for over the documents it takes; left out, its usual name. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content description: >- Markdown telling them what counts, under the title. Left out, the title stands alone. documents: items: $ref: '#/components/schemas/BankProof' type: array title: Documents description: >- The documents taken as proof, in the order the user is offered them. Name none and the step takes any of a statement, a cancelled cheque and a bank letter. additionalProperties: false type: object title: BankProofSettings description: >- How the step asks for proof of the account, and which documents it takes as proof. ConsentedDocument: properties: doc_type: $ref: '#/components/schemas/DigilockerDocType' required: type: boolean title: Required default: true additionalProperties: false type: object required: - doc_type title: ConsentedDocument description: One document the consent asks for, and whether the step needs it back. PhotoSlot: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key label: anyOf: - type: string minLength: 1 - type: 'null' title: Label title: type: string minLength: 1 title: Title content: anyOf: - type: string minLength: 1 - type: 'null' title: Content min_count: type: integer maximum: 10 minimum: 1 title: Min Count default: 1 additionalProperties: false type: object required: - key - title title: PhotoSlot description: One photo the step asks for, and how many of it are needed. MatchBand: properties: pass_at: type: integer maximum: 100 minimum: 0 title: Pass At default: 85 fail_below: type: integer maximum: 100 minimum: 0 title: Fail Below default: 60 scorer: $ref: '#/components/schemas/NameScorer' default: unordered additionalProperties: false type: object title: MatchBand description: >- How close a name has to come to count. A name at or above pass_at matched. One below fail_below is too far off to be the same name. In between it is near, which is what leaves a miss for a person to weigh rather than deciding it either way. The band is worth having because registries and documents write the same party differently: a letter printing 'ABC Recyclers Pvt. Ltd.' against a registered 'ABC RECYCLERS PRIVATE LIMITED' scores 84, too close to reject and not close enough to assert. CarryOnFallback: properties: action: type: string const: carry-on title: Action default: carry-on additionalProperties: false type: object title: CarryOnFallback description: >- Let the journey carry on, as an answer of `{"action": "carry-on"}` would. It takes no wording, because a check that lets the journey through is never shown to the person. TerminateFallback: properties: title: anyOf: - type: string maxLength: 120 minLength: 1 - type: 'null' title: Title description: >- The heading shown in place of the step's title. Where none is given, the step's title is shown. content: anyOf: - type: string maxLength: 500 minLength: 1 - type: 'null' title: Content description: >- The wording shown in place of the step's content. Where none is given, the step's content is shown. action: type: string const: terminate title: Action default: terminate additionalProperties: false type: object title: TerminateFallback description: >- End the journey at the step, as an answer of `{"action": "terminate"}` would, under this wording. RedirectFallback: properties: title: anyOf: - type: string maxLength: 120 minLength: 1 - type: 'null' title: Title description: >- The heading shown in place of the step's title. Where none is given, the step's title is shown. content: anyOf: - type: string maxLength: 500 minLength: 1 - type: 'null' title: Content description: >- The wording shown in place of the step's content. Where none is given, the step's content is shown. action: type: string const: redirect title: Action default: redirect redirect_url: type: string maxLength: 2083 title: Redirect Url description: Where the person is sent. additionalProperties: false type: object required: - redirect_url title: RedirectFallback description: >- End the journey at the step and send the person on, as an answer of `{"action": "redirect"}` would. The link is held to the workflow's list of places a person may be sent, exactly as a redirect your system answers is. A verification is not started, or reset, on a version whose fallback link that list does not allow, and a link the list stops allowing later ends the journey without sending the person anywhere, as `terminate` would. HoldFallback: properties: title: anyOf: - type: string maxLength: 120 minLength: 1 - type: 'null' title: Title description: >- The heading shown in place of the step's title. Where none is given, the step's title is shown. content: anyOf: - type: string maxLength: 500 minLength: 1 - type: 'null' title: Content description: >- The wording shown in place of the step's content. Where none is given, the step's content is shown. action: type: string const: hold title: Action default: hold additionalProperties: false type: object title: HoldFallback description: >- Hold the person on the step until your system answers, under this wording. Nothing stands in for the answer. The step reads as an error the person can try again from, and nothing after it is part of their journey. Trying again puts the check to your system again, so a hold is how the journey waits while you put right whatever kept your system from answering. Declaration: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key description: Identifies the declaration, and names it in the step's answer. label: anyOf: - type: string minLength: 1 - type: 'null' title: Label description: >- This declaration's name in your own system, where your workflow gives it one. It is recorded with the answer, so the same declaration reads the same name on every workflow that puts it. title: anyOf: - type: string minLength: 1 - type: 'null' title: Title description: >- The heading this declaration is presented under, where it needs one of its own. Left out, its wording stands alone. content: type: string minLength: 1 title: Content description: >- The wording beside the tick box, in Markdown, so it can link out to the terms or the policy it refers to. Rendered under the title where the declaration carries one. optional: type: boolean title: Optional description: >- Whether the person may submit without ticking this. An optional declaration records whichever way they left it; every other one has to be ticked before they can submit. default: false default: type: boolean title: Default description: >- Whether the box is presented already ticked, which only an optional declaration may be: accepting one you require is the person's own act. Presentation only, so what is recorded is how they left it. default: false additionalProperties: false type: object required: - key - content title: Declaration description: >- One thing the person states for themselves before submitting, ticked on its own. KindRecord: properties: key: type: string title: Key description: >- Names this kind when a document is sent for it, and on every file provided as it. label: anyOf: - type: string - type: 'null' title: Label description: Your own name for this document, where your workflow carries one. accept: items: $ref: '#/components/schemas/SlotAccept' type: array title: Accept description: >- How this kind arrives: how many files, in what formats. The files must satisfy exactly one. type: object required: - key - label - accept title: KindRecord description: One kind of document a slot takes, as the client addresses and reads it. FieldType: type: string enum: - text - textarea - number - date - boolean - choice - address title: FieldType description: What a form field collects. NamedPattern: type: string enum: - pan - gstin - ifsc - mobile - email - pin-code title: NamedPattern description: Named validation patterns a text field may declare. AskedWhen: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key description: >- The key this gate follows: a field declared earlier in the same form, or a value the form reads. values: anyOf: - items: anyOf: - type: string - type: boolean type: array minItems: 1 - type: 'null' title: Values description: >- The values of that key which ask for this field. The gate holds while the key carries one of them, and a key carrying nothing holds no gate. Give this or `present`. present: anyOf: - type: boolean - type: 'null' title: Present description: >- Follow whether the key carries anything at all rather than which value it carries: `true` asks for the field while it carries a value, `false` while it carries none. This is how a field follows a value plumbed in from a step the journey may never reach, which carries nothing on a journey that did not reach it, whatever it would have carried. Give this or `values`. additionalProperties: false type: object required: - key title: AskedWhen description: >- One gate on a field: the key it follows, and what that key has to carry to ask for this field. DocumentKind: properties: key: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Key description: Identifies the kind of document. label: anyOf: - type: string minLength: 1 - type: 'null' title: Label description: >- This document's name in your own system, where your workflow gives it one. Kinds on different steps may share a label, which is how you find the same document whichever branch of a journey ran. title: anyOf: - type: string minLength: 1 - type: 'null' title: Title description: >- What the person providing it is asked for. A kind names itself to tell it apart from the others of its slot, so the only kind of a slot needs no name of its own and is asked for under the slot's. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content description: >- Markdown telling them what counts, rendered under the title. Left out, the title stands alone. accept: items: $ref: '#/components/schemas/SlotAccept' type: array minItems: 1 title: Accept description: >- The intake shapes for this kind. The files provided as it must satisfy exactly one of them. additionalProperties: false type: object required: - key title: DocumentKind description: >- One kind of document a slot will take, named so a screen can list what counts. The kinds of one slot may arrive differently: a cancelled cheque is one photograph, a bank statement a document of several pages, and one slot takes either. ReadableDocument: properties: kind: $ref: '#/components/schemas/ReadableKind' description: Which document this is, of the ones a step can read. label: anyOf: - type: string minLength: 1 - type: 'null' title: Label description: >- This document's name in your own system, carried on every file provided as it. Documents on different slots may share one, which is how you find the same document whichever branch of a journey ran, and the two documents of a slot taking a choice are told apart by taking different ones. title: anyOf: - type: string minLength: 1 - type: 'null' title: Title description: >- What the person providing it is asked for. A slot taking a choice titles each document so they can be told apart; the only document of a slot is asked for under the slot's own title. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content description: >- Markdown telling them what counts, under the title. Left out, the slot's own wording stands. additionalProperties: false type: object required: - kind title: ReadableDocument description: >- One document a slot takes: what it is, what it is asked for as, and the name you know it by. SlotAccept: properties: types: items: $ref: '#/components/schemas/FileType' type: array minItems: 1 title: Types description: The file types this shape accepts. max: type: integer minimum: 1 title: Max description: The most files this shape accepts. default: 1 min: type: integer minimum: 1 title: Min description: The fewest files this shape accepts. default: 1 additionalProperties: false type: object required: - types title: SlotAccept description: 'One acceptable intake shape for a slot: which file types and how many.' ReadableKind: type: string enum: - arn-registration - aprn-registration - nism-certificate title: ReadableKind description: >- The kinds of document this step knows how to read. A subset of the documents docvue can parse rather than all of them: a balance sheet is parsed for figures a step judges nothing about, where these three are credentials a journey turns on. ValidRule: properties: field: type: string title: Field description: The field of the document this is asked of. unmet: $ref: '#/components/schemas/Unmet' description: >- Whether an unmet check fails the step or is only reported on one that passed. default: fail rule: type: string const: valid title: Rule default: valid warn_within_days: anyOf: - type: integer maximum: 730 minimum: 1 - type: 'null' title: Warn Within Days description: >- Report a document still in force but this close to running out. A date inside the window is reported whatever `unmet` says, because it is not unmet. additionalProperties: false type: object required: - field title: ValidRule description: >- The date in this field has not passed, and is further out than the warning window. The only rule reading no input, because the date it compares against is the day the step is judged. Every other rule holds a record to something the journey was told; this one holds it to the calendar, which is also why it is the only check that can turn from met to unmet with nothing re-uploaded and nothing re-plumbed. MatchesRule: properties: field: type: string title: Field description: The field of the document this is asked of. unmet: $ref: '#/components/schemas/Unmet' description: >- Whether an unmet check fails the step or is only reported on one that passed. default: fail rule: type: string const: matches title: Rule default: matches input: type: string title: Input description: The name you plumb the names to score against under. band: $ref: '#/components/schemas/MatchBand' additionalProperties: false type: object required: - field - input title: MatchesRule description: The name in this field scores against names the step was plumbed. EqualsRule: properties: field: type: string title: Field description: The field of the document this is asked of. unmet: $ref: '#/components/schemas/Unmet' description: >- Whether an unmet check fails the step or is only reported on one that passed. default: fail rule: type: string const: equals title: Rule default: equals input: type: string title: Input description: The name you plumb the identifier to compare against under. additionalProperties: false type: object required: - field - input title: EqualsRule description: The identifier in this field is exactly the one the step was plumbed. BankProof: properties: kind: $ref: '#/components/schemas/BankProofKind' description: Which document this is. label: anyOf: - type: string minLength: 1 - type: 'null' title: Label description: >- This document's name in your own system, carried on every file provided as it. Give the same one to a document asked for on more than one branch of a journey and it reads the same whichever branch ran. title: anyOf: - type: string minLength: 1 - type: 'null' title: Title description: What the user is asked for; left out, its usual name. content: anyOf: - type: string minLength: 1 - type: 'null' title: Content description: >- Markdown telling them what counts, under the title. Left out, the title stands alone. additionalProperties: false type: object required: - kind title: BankProof description: One document the step takes as proof, and what the user is asked for it. DigilockerDocType: type: string enum: - aadhaar - pan - driving_license title: DigilockerDocType description: Document types that can be requested from DigiLocker. NameScorer: type: string enum: - ordered - unordered - subset title: NameScorer description: >- How two names are compared. Which one is right follows from what the comparison is for. FileType: type: string enum: - pdf - image title: FileType description: The file families a document slot may accept. Unmet: type: string enum: - fail - report title: Unmet description: What an unmet check does to the step. BankProofKind: type: string enum: - statement - cheque - letter title: BankProofKind description: The documents that evidence a bank account. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.