Tracking verifications

Reading one verification answers a question about one subject. These endpoints answer questions about your account: which journeys you can run, how the runs on them stand, how many of them your own checks stopped, and which records make up a number.

Endpoint	Answers
`GET /workflows`	Which workflows are configured for you, and where each stands on its limits.
`GET /verifications/summary`	How many of your verifications are in which status.
`GET /verifications/gated-runs`	How many runs your gate checks stopped, per workflow and per gate.
`GET /verifications`	Which verifications those are, a page at a time.

All of them answer for your key’s environment alone. A uat key counts and lists the runs on your uat workflows and a production key those on your production ones, so a total you read is a total within one environment. See Environments.

Your workflows

GET /workflows lists every workflow in your key’s environment: the key you name when creating a verification, its name, its mode, how long a verification created on it now holds a user’s data, how many steps it declares, and where it stands on both of the limits its verifications are held to.

{
  "workflows": [
    {
      "key": "merchant-onboarding",
      "name": "Merchant onboarding",
      "mode": "hosted",
      "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 }
    },
    {
      "key": "vendor-verification",
      "name": "Vendor verification",
      "mode": "staged",
      "expires_after_days": 30,
      "step_count": 5,
      "environment": "production",
      "credits": { "granted": 100, "consumed": 100, "expired": 0, "revoked": 0, "remaining": 0, "expiring": [] },
      "runs": { "live": 3, "limit": 25 }
    }
  ]
}

credits is what the workflow was sold and what its runs have used, and runs is how many verifications it has going against how many it may. This is the endpoint to watch to see a workflow running low: reading it uses no credit, and vendor-verification above is out and will refuse a create with 402. Every workflow reports runs, an instant one included: its verifications are open for as long as their checks run. See Credits and limits. For the steps themselves, read one workflow with GET /workflows/{workflow_key}. That view is reference material rather than a stable contract, and Verification lifecycle says why. A workflow taken out of use is not listed, because you can no longer create a verification on it. The verifications that ran it stay readable and go on naming it as their workflow_key, so a key you read on a record may not appear here. Every key you can read is still one you can count and filter on.

Counting them

GET /verifications/summary counts every verification in your key’s environment by status, in total and split by the workflow it runs:

{
  "counts": {
    "total": 1292,
    "open": 42,
    "submitted": 3,
    "completed": 1180,
    "cancelled": 9,
    "gated": 8,
    "failed": 0,
    "expired": 50
  },
  "workflows": [
    {
      "workflow_key": "merchant-onboarding",
      "counts": { "total": 1006, "open": 30, "submitted": 2, "completed": 920, "cancelled": 8, "gated": 6, "failed": 0, "expired": 40 }
    },
    {
      "workflow_key": "vendor-verification",
      "counts": { "total": 286, "open": 12, "submitted": 1, "completed": 260, "cancelled": 1, "gated": 2, "failed": 0, "expired": 10 }
    }
  ]
}

total is the sum of the six statuses, in the whole and in each workflow, so nothing is counted twice and nothing is left out. Statuses says what each one means. A workflow appears once it has a verification in what was counted, so one nobody has been sent through is absent from workflows while still being listed by GET /workflows.

These are counts of statuses, not of outcomes. A verification counted as completed is one that finished, not one that passed: a user can complete a journey with a step that failed. And because expiry supersedes every ending, a completed run stops being counted as completed once it expires. Read a verification, or list them, to see what a count is made of.

Counting a period

from and to narrow both the summary and the list to verifications created in that period. Days are IST and both ends are inclusive, so from=2026-08-01&to=2026-08-31 counts the runs that began in August and reports where each of them stands now. Leave either out to leave that end open; leave both out and every verification you have ever created is counted.

Counting gated runs

GET /verifications/gated-runs counts the runs a gate check of yours stopped, in total, per workflow and per gate that stopped them:

{
  "total": 8,
  "workflows": [
    {
      "workflow_key": "merchant-onboarding",
      "total": 6,
      "gates": [
        { "step_key": "already-a-dealer", "stopped": 4 },
        { "step_key": "gst-onboarded", "stopped": 2 }
      ]
    },
    {
      "workflow_key": "vendor-verification",
      "total": 2,
      "gates": [{ "step_key": "gst-onboarded", "stopped": 2 }]
    }
  ]
}

Every run a gate stopped is counted once, however the verification has moved on since. Resetting a gated verification does not take its run out of the count, and if the gate stops the run the reset began, that is counted again. A gated verification that has since expired or been purged is still counted. A workflow whose gates have stopped nothing, and a gate that has stopped nothing, are absent. from and to narrow the count to runs stopped in that period, read against the day the gate stopped each one rather than the day its verification was created. Days are IST and both ends are inclusive.

This is not the gated figure in the summary. The summary counts the verifications standing in gated now, by the day each was created, so a gated verification you reset or that expired is no longer counted there. Count gated runs here.

Listing them

GET /verifications returns a page of records without their steps: what each one is, who completes it, where it stands, when it got there, and how its callback ended.

{
  "verifications": [
    {
      "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",
      "callback": { "status": "delivered", "settled_at": "2026-08-10T14:41:09", "reason": null }
    }
  ],
  "next_cursor": "MjAyNi0wOC0wM1QwOTo0MToyN3wwZThhNWQyNC0zZjcxLTRjNjgtOWI1Mi04ZDE3YTQwZTVjOTM="
}

An entry carries no steps, no progress, no context, and no mobile number. Read the verification by id for those; Reading the result covers the whole record. version is the version of the workflow the verification runs. Listing a workflow’s open verifications therefore shows which of them are still walking an earlier version than the latest, which are the ones to decide about when a workflow changes. See Versions.

Narrowing the list

Parameter	Effect
`status`	Only these statuses. Repeat the parameter for more than one, as `status=open&status=submitted`.
`workflow_key`	Only verifications on the workflow with that key, in use or withdrawn. A key that has never been one of yours is refused with `400`, and one of yours in the other environment with `403`.
`reference_user_id`	Only verifications you created under that reference.
`from`, `to`	Only verifications created in that period, as above.
`limit`	Records per page, 1 to 200. Defaults to 50.
`cursor`	The `next_cursor` of the previous page.

A reference is unique to a live verification within one workflow, so reference_user_id on its own gathers that subject’s run of each of your workflows, along with any expired record still holding the reference. Name workflow_key as well for one particular run.

Paging

Read next_cursor from a page and pass it back as cursor to get the page after it. The page that carries null is the last one:

GET /verifications?status=open&limit=50
GET /verifications?status=open&limit=50&cursor=MjAyNi0wOC0wM1QwOTo0MToyN3ww...

Keep the other parameters the same across a walk; a cursor marks a position in the list you were reading, not a filter of its own. Paging is keyed on the record’s position rather than on an offset, so a verification you create while partway through a walk never shifts a later page. Cursors are opaque: pass one back as you received it and do not build anything out of its contents.

Finding a record from your own reference

reference_user_id is your identifier, and it is the handle that survives a record expiring. Filtering the list on it finds the verification without your having stored our id:

GET /verifications?workflow_key=merchant-onboarding&reference_user_id=merchant-42

Catching up on callbacks you missed

Privue posts one callback per submission and one per run a gate check stopped, and the verification completes, or stays gated, whether or not it was delivered, so an endpoint that was down loses those notifications. The list is how you find them again: read the period your endpoint was down, and callback on each entry says which records you were told about.

GET /verifications?status=completed&from=2026-08-09&to=2026-08-10

An entry whose callback.status reads failed is a finished verification you were never told about, and reason says what our attempts ran into. Read status=gated over the same period for the gated runs you missed. See Callbacks.

Get started

Run a verification

Read the result

Go live

Reference

Tracking verifications

Your workflows

Counting them

Counting a period

Counting gated runs

Listing them

Narrowing the list

Paging

Finding a record from your own reference

Catching up on callbacks you missed

​Your workflows

​Counting them

​Counting a period

​Counting gated runs

​Listing them

​Narrowing the list

​Paging

​Finding a record from your own reference

​Catching up on callbacks you missed

Your workflows

Counting them

Counting a period

Counting gated runs

Listing them

Narrowing the list

Paging

Finding a record from your own reference

Catching up on callbacks you missed