> ## 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 verifications > List the verifications in your API key's environment, newest created first. Every verification without its steps: what it is, who completes it, where it stands, when it got there, and how its callback ended. Narrow it by status, by workflow, by the reference you started it under, or to a period with `from` and `to`, which are read against the day a verification was started. Read `next_cursor` from a page and pass it back as `cursor` for the page after it; the page that carries none is the last. A verification started while you are partway through never shifts a later page, so a walk of the list sees each record once. Filtering on `reference_user_id` alone gathers every record carrying it, expired ones included. On a hosted or staged workflow one live verification holds it, so that is one run of each of those workflows; on an instant workflow it is a label, so every verification you ran under it is listed. Name the workflow as well to narrow the list to that one. Every key you can read on a record is a key you can filter on, a workflow no longer in use included, so a journey withdrawn from service still lists the verifications that ran it. Read a verification by id for its steps, what they collected, and why anything did not pass. ## OpenAPI ````yaml /verification/api-reference/openapi.json get /verifications 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: /verifications: get: tags: - Results summary: List verifications description: >- List the verifications in your API key's environment, newest created first. Every verification without its steps: what it is, who completes it, where it stands, when it got there, and how its callback ended. Narrow it by status, by workflow, by the reference you started it under, or to a period with `from` and `to`, which are read against the day a verification was started. Read `next_cursor` from a page and pass it back as `cursor` for the page after it; the page that carries none is the last. A verification started while you are partway through never shifts a later page, so a walk of the list sees each record once. Filtering on `reference_user_id` alone gathers every record carrying it, expired ones included. On a hosted or staged workflow one live verification holds it, so that is one run of each of those workflows; on an instant workflow it is a label, so every verification you ran under it is listed. Name the workflow as well to narrow the list to that one. Every key you can read on a record is a key you can filter on, a workflow no longer in use included, so a journey withdrawn from service still lists the verifications that ran it. Read a verification by id for its steps, what they collected, and why anything did not pass. operationId: read_verifications_verifications_get parameters: - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: Verifications per page. default: 50 title: Limit description: Verifications per page. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: '`next_cursor` from the previous page.' title: Cursor description: '`next_cursor` from the previous page.' - name: status in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/VerificationStatus' - type: 'null' description: >- Only these statuses. Repeat the parameter for more than one; omit it for every status. title: Status description: >- Only these statuses. Repeat the parameter for more than one; omit it for every status. - name: workflow_key in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Only verifications on the workflow with this key, in use or withdrawn. title: Workflow Key description: >- Only verifications on the workflow with this key, in use or withdrawn. - name: reference_user_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only verifications you created under this reference. title: Reference User Id description: Only verifications you created under this reference. - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: First day to include, in IST, inclusive. title: From description: First day to include, in IST, inclusive. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Last day to include, in IST, inclusive. title: To description: Last day to include, in IST, inclusive. responses: '200': description: One page of verifications, newest created first. content: application/json: schema: $ref: '#/components/schemas/VerificationPage' example: verifications: - id: 6a2f0c91-3b7e-4d15-8c4a-0f9e2b7d1c58 mode: staged status: open workflow_key: vendor-verification version: 1 reference_user_id: VENDOR-4471 created_at: '2026-08-27T11:02:09' run_requested_at: '2026-08-27T11:06:40' submitted_at: null completed_at: null cancelled_at: null gated_at: null gated_by_step: null failed_at: null expired_at: null expired_by: null last_activity_at: '2026-08-27T11:06:40' resets: 0 callback: null - id: 3f2504e0-4f89-41d3-9a0c-0305e82c3301 mode: hosted status: completed workflow_key: merchant-onboarding version: 2 reference_user_id: merchant-42 created_at: '2026-08-10T14:02:11' run_requested_at: null submitted_at: '2026-08-10T14:41:06' completed_at: '2026-08-10T14:41:09' cancelled_at: null gated_at: null gated_by_step: null failed_at: null expired_at: null expired_by: null last_activity_at: '2026-08-10T14:41:06' resets: 0 callback: status: delivered settled_at: '2026-08-10T14:41:09' reason: null - id: 9c1f7b30-5d84-4e26-a0f3-7b58c1d94e62 mode: hosted status: cancelled workflow_key: merchant-onboarding version: 2 reference_user_id: merchant-41 created_at: '2026-08-09T10:37:52' run_requested_at: null submitted_at: null completed_at: null cancelled_at: '2026-08-10T15:02:44' gated_at: null gated_by_step: null failed_at: null expired_at: null expired_by: null last_activity_at: '2026-08-10T14:14:37' resets: 0 callback: null - id: 0e8a5d24-3f71-4c68-9b52-8d17a40e5c93 mode: hosted status: expired workflow_key: merchant-onboarding version: 2 reference_user_id: merchant-17 created_at: '2026-08-03T09:41:27' run_requested_at: null submitted_at: '2026-08-10T14:41:06' completed_at: '2026-08-10T14:41:09' cancelled_at: null gated_at: null gated_by_step: null failed_at: null expired_at: '2026-08-17T15:00:04' expired_by: retention last_activity_at: '2026-08-10T14:41:06' resets: 0 callback: status: delivered settled_at: '2026-08-10T14:41:09' reason: null next_cursor: >- MjAyNi0wOC0wM1QwOTo0MToyN3wwZThhNWQyNC0zZjcxLTRjNjgtOWI1Mi04ZDE3YTQwZTVjOTM= '400': description: >- No workflow of yours has ever carried that key, whether or not it is still in use. The code is `workflow-not-found`. content: application/json: example: code: workflow-not-found detail: client 'acme' has no 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: >- A query parameter is not valid: an unknown status, a period that runs backwards, or a cursor that came from somewhere other than a page of this list. The code is one of `page-cursor-invalid`, `window-invalid` or `request-invalid`. content: application/json: example: code: page-cursor-invalid detail: 'cursor: not one we issued' 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: VerificationStatus: type: string enum: - open - submitted - completed - cancelled - gated - expired - failed title: VerificationStatus description: Where a verification stands. VerificationPage: properties: verifications: items: $ref: '#/components/schemas/VerificationEntry' type: array title: Verifications description: The verifications on this page, newest created first. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: >- Pass as `cursor` to read the page after this one. Null on the last page, which is how a walk of the list knows to stop. type: object required: - verifications - next_cursor title: VerificationPage description: One page of verifications, newest first. 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. VerificationEntry: properties: id: type: string format: uuid title: Id description: The verification's id, which reads the whole record. mode: $ref: '#/components/schemas/WorkflowMode' description: 'How it was conducted: `hosted`, `staged` or `instant`.' status: $ref: '#/components/schemas/VerificationStatus' description: Where the verification stands, as the record reports it. workflow_key: type: string title: Workflow Key description: The workflow it runs. version: type: integer minimum: 1 title: Version description: Which version of the workflow it runs. reference_user_id: type: string title: Reference User Id description: Your identifier for it, as you supplied it when creating it. created_at: type: string format: date-time title: Created At description: When the verification was created. run_requested_at: anyOf: - type: string format: date-time - type: 'null' title: Run Requested At description: >- When you asked for the checks to run, on a verification you supplied yourself. Null otherwise. submitted_at: anyOf: - type: string format: date-time - type: 'null' title: Submitted At description: When the verification was submitted, if it has been. completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: When the verification completed, if it has. cancelled_at: anyOf: - type: string format: date-time - type: 'null' title: Cancelled At description: When the verification was cancelled, if it was. gated_at: anyOf: - type: string format: date-time - type: 'null' title: Gated At description: When a check of yours stopped the journey, if one did. gated_by_step: anyOf: - type: string - type: 'null' title: Gated By Step description: >- The step whose check stopped the journey, if one did. Set and cleared with `gated_at`. failed_at: anyOf: - type: string format: date-time - type: 'null' title: Failed At description: When the verification was marked failed, if it was. expired_at: anyOf: - type: string format: date-time - type: 'null' title: Expired At description: When the verification expired, if it has. expired_by: anyOf: - $ref: '#/components/schemas/ExpiryCause' - type: 'null' description: 'What expired it: `retention` or `client`. Null until it expires.' last_activity_at: type: string format: date-time title: Last Activity At description: >- When the verification was last acted on, which the retention window is counted from. resets: type: integer title: Resets description: >- How many times this verification has been reset, whether or not those resets drew on the workflow's allowance. A verification holds no allowance of its own. callback: anyOf: - $ref: '#/components/schemas/CallbackRecord' - type: 'null' description: >- How the callback for this verification's run ended, submitted or gated. Null until the callback settles, and on every verification of a workflow with no callback endpoint registered. type: object required: - id - mode - status - workflow_key - version - reference_user_id - created_at - run_requested_at - submitted_at - completed_at - cancelled_at - gated_at - gated_by_step - failed_at - expired_at - expired_by - last_activity_at - resets - callback title: VerificationEntry description: One verification as it stands, without its steps. 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. ExpiryCause: type: string enum: - retention - client title: ExpiryCause description: What deleted a verification's data and closed the record for audit. CallbackRecord: properties: status: $ref: '#/components/schemas/CallbackStatus' description: >- delivered once your endpoint accepted the callback; failed once every attempt at it was spent without one being accepted. settled_at: type: string format: date-time title: Settled At description: When the callback was accepted, or when the attempts ran out. reason: anyOf: - type: string - type: 'null' title: Reason description: >- Why no attempt was accepted, on a failed callback. Null on a delivered one. type: object required: - status - settled_at - reason title: CallbackRecord description: How the callback for this verification ended. CallbackStatus: type: string enum: - delivered - failed title: CallbackStatus description: >- How the hand-off to the client ended. Absent while none has been attempted, or none is owed. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.