CPR Selective State Reset API

Overview

The CPR /selective-state-reset API selectively clears module data and resets the user's journey state for one or more journey steps (which refer to an entire branch, e.g., Digilocker step, eSign step), along with any steps that depend on them (cascade).

This is an internal API used by the dashboard to allow selectively resetting steps without resetting the entire state.

Prerequisites

• The workflow should be non-linear.
• indexPage property should be added in the workflow.
• stepId has been added on all modules of the workflow.
• properties.serverSideResume.stepIdDependencies is properly configured in the workflow properties.

Request details

note

This is an internal API. Access is restricted to authorized services only.

cURL example

curl -X POST 'https://ind-state.idv.hyperverge.co/v2/internal/selective-state-reset' \
  -H 'Content-Type: application/json' \
  -H 'appId: any_app_id' \
  -H 'appKey: any_app_key' \
  -d '{
    "appId": "your_app_id",
    "transactionId": "your_transaction_id",
    "workflowId": "your_workflow_id",
    "selectedStepIds": ["id_card_validation"]
  }'

Base URL: https://ind-state.idv.hyperverge.co URL: /api/v2/internal/selective-state-reset Method: POST

Authentication

Header	Required
appId	yes
appKey	yes
authorization	yes (if appKey not provided)

Request body

Field	Type	Required	Description	Example
appId	String	Yes	The appId.	"55a3a6"
transactionId	String	Yes	The transaction ID to reset.	"txn_abc123"
workflowId	String	Yes	The workflow ID.	"user_main_onboarding"
selectedStepIds	Array of Strings	Yes (min 1)	List of step IDs to reset. Dependent steps are cascaded automatically using properties.serverSideResume.stepIdDependencies.	["id_card_validation"]

Sample responses

Success — modules cleared

{
  "status": "success",
  "statusCode": 200,
  "code": "resource_updated_successfully"
}

Success — no modules to clear

Returned when the provided selectedStepIds do not map to any modules in the workflow or module execution order (e.g., unknown step IDs).

{
  "status": "success",
  "statusCode": 200,
  "code": "resource_not_found_no_action_taken"
}

Error responses

Status code	Error scenario	Response structure
400	Missing required field: appId	{"status": "failure", "statusCode": 400, "errorCode": "invalid_request_body", "error": "\"appId\" is required"}
400	Missing required field: transactionId	{"status": "failure", "statusCode": 400, "errorCode": "invalid_request_body", "error": "\"transactionId\" is required"}
400	Missing required field: workflowId	{"status": "failure", "statusCode": 400, "errorCode": "invalid_request_body", "error": "\"workflowId\" is required"}
400	Missing required field: selectedStepIds	{"status": "failure", "statusCode": 400, "errorCode": "invalid_request_body", "error": "\"selectedStepIds\" is required"}
400	Empty selectedStepIds array	{"status": "failure", "statusCode": 400, "errorCode": "invalid_request_body", "error": "\"selectedStepIds\" must contain at least 1 items"}
404	Transaction state not found	{"status": "failure", "statusCode": 404, "errorCode": "state_not_found"}
410	Transaction state has expired	{"status": "failure", "statusCode": 410, "errorCode": "state_expired"}
400	Workflow has no index page configured	{"status": "failure", "statusCode": 400, "errorCode": "index_page_not_found"}
500	Internal server error during DB transaction	{"status": "failure", "statusCode": 500, "errorCode": "internal_server_error"}

Deep dive — working of the API

Request validation

1. All required fields (appId, transactionId, workflowId, selectedStepIds) must be present.
2. selectedStepIds must be a non-empty array of strings.

Step resolution & cascade logic

The API computes the full set of modules to clear via BFS on the stepIdDependencies graph:

1. Starting from each step in selectedStepIds, it discovers all dependent steps recursively.
2. For each resolved step, all associated module IDs are collected via stepIdToModulesMap.
3. Duplicates are removed; the final set is the union of all modules across all affected steps.

Example: if id_card_validation → [aml_1] and aml_1 → [selfie_validation], then resetting id_card_validation cascades to clear modules for aml_1 and selfie_validation as well.

State update logic

The reset runs inside a single DB transaction:

1. transactionMetadata.status is removed from the stored state (so the transaction is no longer in an end state).
2. Module data rows for all affected modules are deleted.

Effect on subsequent GET calls

After a successful reset, the next get-transaction-state call will:

• Return a moduleExecutionOrder and executionPath trimmed to only include modules that were not reset.
• Not include status in transactionMetadata (cleared by the reset).

Flow diagram

flowchart TD
    st([Start])
    e([End])
    op1[Validate Request Schema]
    op2[Fetch Transaction State]
    op3["Fetch Workflow Config<br/>index pages + stepIdDependencies<br/>+ stepIdToModulesMap"]
    op4["BFS: Resolve all steps<br/>to reset incl. dependents"]
    op5["Collect module IDs<br/>for all resolved steps"]
    op6["DB Transaction:<br/>1. Omit status from transactionMetadata<br/>2. Delete module data rows<br/>3. Commit"]
    cond1{Valid Request?}
    cond2{State exists<br/>& not expired?}
    cond3{Index page<br/>found?}
    cond4{Any modules<br/>to clear?}

    st --> op1 --> cond1
    cond1 -- No --> e
    cond1 -- Yes --> op2 --> cond2
    cond2 -- "No<br/>state_not_found /<br/>state_expired" --> e
    cond2 -- Yes --> op3 --> cond3
    cond3 -- "No<br/>index_page_not_found" --> e
    cond3 -- Yes --> op4 --> op5 --> cond4
    cond4 -- "No<br/>resource_not_found_no_action_taken" --> e
    cond4 -- Yes --> op6 --> e

Analytics events

The API logs the following events to the cpr_analytics table:

Event name	When triggered
selective-state-reset-started	Request received.
selective-state-reset-state-not-found	Transaction state not found in DB.
selective-state-reset-state-expired	Transaction state has expired.
selective-state-reset-no-modules-to-clear	selectedStepIds resolve to no modules.
selective-state-reset-rollback-failed	DB transaction rollback failed.
selective-state-reset-success	Modules cleared and state updated successfully.