CPR Bulk Reset API

Overview

The CPR /delete-transaction-state/bulk API is designed to bulk delete CPR transaction states based on workflow versions and application status. This is an internal API used for resetting multiple transactions at once, typically when a workflow version needs to be deprecated.

Request details

note

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

cURL example

curl --location --request DELETE 'https://ind-state.dev.hyperverge.co/v2/internal/delete-transaction-state/bulk' \
  --header 'Content-Type: application/json' \
  --header 'appId: ' \
  --header 'appKey: ' \
  --data-raw '{
    "appId": "your_app_id",
    "workflowId": "your_workflow_id",
    "workflowVersions": ["1.0.0"],
    "applicationStatusToReset": ["user_cancelled", "error", "auto_declined"],
    "email": "your.email@hyperverge.com",
    "clientId": "manual-test"
  }'

Base URL: https://ind-state.idv.hyperverge.co URL: /api/v2/internal/delete-transaction-state/bulk Method: DELETE

Authentication

This API requires authentication headers.

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

Request body

Field	Type	Required	Description	Example	Default
appId	String	Yes	The application ID.	"55a3a6"
workflowId	String	Yes	The workflow ID.	"user_main_onboarding"
workflowVersions	Array of Strings	Yes	List of workflow versions to delete. Must follow semver format (x.y.z).	["1.0.0", "1.1.0"]
applicationStatusToReset	Array of Strings	No	Filter deletion by transaction status. If empty, deletes all matching records regardless of status.	["user_cancelled", "error"]	["user_cancelled", "error", "auto_declined"]
email	String	Yes	Email of the person initiating the bulk reset.	"user@hyperverge.co"
clientId	String	Yes	Identifier of the client/system triggering the reset.	"HV"

Allowed status values

applicationStatusToReset accepts the following values:

Status	Description
needs_review	Transaction pending manual review.
auto_approved	Transaction automatically approved.
auto_declined	Transaction automatically declined.
user_cancelled	Transaction cancelled by user.
error	Transaction encountered an error.
manually_approved	Transaction manually approved by reviewer.
manually_declined	Transaction manually declined by reviewer.

Behaviour notes:

• If applicationStatusToReset is sent as an empty array (applicationStatusToReset: []), the API deletes all records matching appId, workflowId, and workflowVersions regardless of status.
• If applicationStatusToReset is not sent, the API takes the default values: ["user_cancelled", "error", "auto_declined"].

Sample responses

Success — records deleted

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "deletedRecords": [
      { "transactionId": "txn_abc123" },
      { "transactionId": "txn_def456" },
      { "transactionId": "txn_ghi789" }
    ],
    "count": 3
  }
}

Success — no records found

{
  "status": "success",
  "statusCode": 200,
  "code": "resource_not_found_no_action_taken",
  "result": {
    "deletedRecords": [],
    "count": 0
  }
}

Error responses

Status code	Error scenario	Response structure
400	Missing required field: appId	{"status": "failure", "statusCode": 422, "error": "\"appId\" is required"}
400	Missing required field: workflowId	{"status": "failure", "statusCode": 422, "error": "\"workflowId\" is required"}
400	Missing required field: workflowVersions	{"status": "failure", "statusCode": 422, "error": "\"workflowVersions\" is required"}
400	Empty workflowVersions array	{"status": "failure", "statusCode": 422, "error": "\"workflowVersions\" must contain at least 1 items"}
400	Invalid version format	{"status": "failure", "statusCode": 422, "error": "\"workflowVersions[0]\" fails to match the required pattern"}
400	Invalid status value	{"status": "failure", "statusCode": 422, "error": "\"applicationStatusToReset[0]\" must be one of [needs_review, auto_approved, ...]"}
400	Missing required field: email	{"status": "failure", "statusCode": 422, "error": "\"email\" is required"}
400	Invalid email format	{"status": "failure", "statusCode": 422, "error": "\"email\" must be a valid email"}
400	Missing required field: clientId	{"status": "failure", "statusCode": 422, "error": "\"clientId\" is required"}

Deep dive — working of the API

Request validation

1. All required fields (appId, workflowId, workflowVersions, email, clientId) must be present.
2. workflowVersions must be a non-empty array with valid semver format (x.y.z).
3. applicationStatusToReset values must be from the allowed status map.
4. email must be a valid email format.

Deletion logic

The API builds a database query with the following conditions:

1. appId equals the provided appId.
2. workflowId equals the provided workflowId.
3. workflowVersion is in the provided workflowVersions array.
4. If applicationStatusToReset is provided and non-empty, additionally filters by status.

Status filtering behaviour

When applicationStatusToReset is provided:

• Deletes records where transactionMetadata.status matches any value in the array.
• Also deletes records where transactionMetadata is NULL.
• Also deletes records where transactionMetadata.status is NULL or empty.
• This ensures transactions without a status are also cleaned up.
• If applicationStatusToReset is provided as empty, it takes the default values.

Flow diagram

flowchart TD
    st([Start])
    e([End])
    op1[Validate Request Schema]
    op2[Build Delete Query]
    op3[Execute Delete with Filters]
    op4[Return Deleted Records]
    cond1{Valid Request?}
    cond2{Records Found?}

    st --> op1 --> cond1
    cond1 -- Yes --> op2 --> op3 --> cond2
    cond1 -- No --> e
    cond2 -- Yes --> op4 --> e
    cond2 -- No --> e

Analytics events

The API logs the following events to the cpr_analytics table:

Event name	When triggered	Additional fields
delete-transaction-state-versions-started	Request received.	appId, workflowId, workflowVersions, status, email
delete-transaction-state-versions-no-records-found	No matching records.	appId, workflowId, workflowVersions, status, email
delete-transaction-state-versions-success	Records deleted.	appId, workflowId, workflowVersions, status, email, deletedRowsCount