> ## 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. # List your workflows > List the workflows you can start a verification on. One entry per workflow in your API key's environment, naming the `workflow_key` a create takes, how it is conducted, how long a verification on it holds a user's data, how many steps it declares, and where it stands on each of the limits its verifications are held to. Read a single workflow for the steps themselves. A key is for one environment and reaches only that one's workflows, so a `uat` key lists your test journeys and a `production` key lists your real ones. A workflow that has been taken out of use is not listed. The verifications that ran it stay readable, and go on naming it as their `workflow_key`. ## OpenAPI ````yaml /verification/api-reference/openapi.json get /workflows 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: get: tags: - Workflows summary: List your workflows description: >- List the workflows you can start a verification on. One entry per workflow in your API key's environment, naming the `workflow_key` a create takes, how it is conducted, how long a verification on it holds a user's data, how many steps it declares, and where it stands on each of the limits its verifications are held to. Read a single workflow for the steps themselves. A key is for one environment and reaches only that one's workflows, so a `uat` key lists your test journeys and a `production` key lists your real ones. A workflow that has been taken out of use is not listed. The verifications that ran it stay readable, and go on naming it as their `workflow_key`. operationId: read_workflows_workflows_get responses: '200': description: Every workflow your API key's environment holds. content: application/json: schema: $ref: '#/components/schemas/WorkflowList' example: workflows: - key: merchant-onboarding name: Merchant onboarding mode: hosted version: 3 expires_after_days: 30 step_count: 12 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' - key: vendor-verification name: Vendor verification mode: staged version: 1 expires_after_days: 30 environment: production credits: granted: 100 consumed: 100 expired: 0 revoked: 0 remaining: 0 expiring: [] runs: live: 3 limit: 25 resets: granted: 20 drawn: 2 expired: 0 revoked: 0 remaining: 18 expiring: - amount: 18 'on': '2027-06-30' step_count: 5 '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 API key is valid but not enrolled for verifications, or is not set up for exactly one of `uat` and `production`. Ask us to reissue it. The code is `client-not-enrolled`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: client-not-enrolled detail: >- no active verification client 4b8f21c6-59ad-4a70-9e11-7c3d0a52f8b4 '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: WorkflowList: properties: workflows: items: $ref: '#/components/schemas/WorkflowSummary' type: array title: Workflows description: Your workflows, ordered by key. type: object required: - workflows title: WorkflowList description: The workflows configured for you. 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. WorkflowSummary: 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. step_count: type: integer title: Step Count description: >- How many steps the latest version declares, of which any one user walks those that apply to 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. type: object required: - key - name - mode - version - expires_after_days - step_count - environment - credits - runs - resets title: WorkflowSummary description: >- One workflow configured for you, as it appears in a list, read at its latest version. 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. 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. 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`. 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. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.