Programmatically Validate and Verify Requests

When a data subject submits a privacy request (such as an Access or Deletion request), regulations require organizations to verify the requestor’s identity before retrieving or deleting personal data. This initial screening stage is referred to as the Verification Stage (VERIFY).

In this tutorial, you will learn how to programmatically validate a consumer’s identity and transition a request from the verification stage to the data collection stage (COLLECT) using the Admin API.

In this article, you'll learn:

• Retrieve the verification stage status of a privacy request
• Trigger the programmatically validated identity action
• Transition requests smoothly to downstream data collection workflows

Scenario

Your organization uses a third-party identity verification provider (such as Experian, ID.me, or Okta). Once the consumer completes verification successfully on that platform, a webhook triggers your custom script. Validate the request programmatically to automatically move it into the processing pipeline without manual DPO intervention.

---

1. The Verification Lifecycle

By default, newly submitted requests start in the VERIFY processing stage. Until the identity of the requestor is verified:

1. Data collection scanning is blocked to prevent accidental exposure of personal data.
2. Compliance timers (dueDays) continue to count down.

Once you have verified the identity out-of-band or via an external IDP, you invoke the verify action API to transition the request’s processingStage to COLLECT.

---

2. Triggering Programmatic Verification

To verify a request, issue a POST request to the verification action endpoint.

HTTP Endpoint

POST /api/prm/{tenant}/requests/{requestId}/stages/verify/actions/verify

Path Parameters

Parameter	Type	Required	Description
tenant	String	Yes	Your organization’s tenant slug.
requestId	String	Yes	The ID of the request to be verified (e.g., req_841203).

Request Headers

Pass your administrative API key in the X-API-Key header (refer to the Authentication Guide on how to generate this key):

X-API-Key: <YOUR_API_KEY>
Content-Type: application/json

Request Body

The API does not require a complex payload for verification. You pass an empty JSON object:

{}

---

3. Code Examples

Select your preferred language to see how to programmatically verify a request via the Admin API:

Python

import requests

url = "https://bigidprivacy.cloud/api/prm/my-tenant/requests/req_841203/stages/verify/actions/verify"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={})
print(response.json())

JavaScript

const url = 'https://bigidprivacy.cloud/api/prm/my-tenant/requests/req_841203/stages/verify/actions/verify';
const headers = {
  'X-API-Key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
};

async function verifyRequest() {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify({})
    });
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error verifying request:', error);
  }
}

verifyRequest();

Response (200 OK):

The API responds with a successful transition message, reflecting that the request has now entered the next stage.

{
  "requestId": "req_841203",
  "action": "verify",
  "status": "SUCCESS",
  "newProcessingStage": "COLLECT",
  "timestamp": "2026-08-12T14:48:00.000Z"
}

---

4. Verifying via an External Agent (Alternate)

If verification is performed by a dedicated validation script acting as an agent, you can also log the agent’s meta-information by targeting the verify-agent endpoint:

POST /api/prm/{tenant}/requests/{requestId}/stages/verify/actions/verify-agent

Request Payload:

{
  "agentName": "OktaIDV-Automation",
  "verificationScore": 98,
  "transactionId": "tx_abc123789"
}

---

Handling Common Errors

If you attempt to verify a request that has already been verified or is not in the VERIFY stage, the server will block the transition.

Response (403 Forbidden):

{
  "message": "User has insufficient permissions or request is not in VERIFY stage",
  "status": 403
}

Response (404 Not Found):

If the requestId does not exist or the tenant is misspelled:

{
  "message": "Request req_841203 not found",
  "status": 404
}