Status Check API

Use this API to fetch the current VKYC session status for a customer with the unique_id (VKYC reference) returned by the Customer Session Creation API.

GEThttps://sandbox/api/v1/vkyc/vcip-status/external/{unique_id}/

Content-Type: application/json

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <access_token> from the Auth Token API.

Path parameter

Parameter	Type	Required	Description
unique_id	string	Yes	VKYC reference number returned when the session was created.

Example

GET/api/v1/vkyc/vcip-status/external/{unique_id}/

curl --location 'https://sandbox/api/v1/vkyc/vcip-status/external/VYC9000001/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>'

200

{
"event": "vcip.application.verified_by_agent",
"timestamp": "2025-07-13T12:45:00Z",
"trace_id": "trace_agent_verified_001",
"VKYC_ref_id": "VYC9000001",
"customer_ref": "CUST-001",
"data": {
  "verified_by": "AGENT001",
  "verified_at": "2025-07-13T12:44:30Z",
  "status": "VERIFIED"
}
}

Response examples

200 OK — agent verified

{
  "event": "vcip.application.verified_by_agent",
  "timestamp": "2025-07-13T12:45:00Z",
  "trace_id": "trace_agent_verified_001",
  "VKYC_ref_id": "VYC9000001",
  "customer_ref": "CUST-001",
  "data": {
    "verified_by": "AGENT001",
    "verified_at": "2025-07-13T12:44:30Z",
    "status": "VERIFIED"
  }
}

200 OK — agent rejected

{
  "event": "vcip.application.rejected_by_agent",
  "timestamp": "2025-07-13T12:50:00Z",
  "trace_id": "trace_agent_rejected_002",
  "VKYC_ref_id": "VYC9000002",
  "customer_ref": "CUST-002",
  "data": {
    "rejected_by": "AGENT002",
    "rejected_at": "2025-07-13T12:49:55Z",
    "rejection_reason": "id_mismatch",
    "rejection_remark": "PAN details do not match Aadhaar",
    "status": "REJECTED"
  }
}

200 OK — checker approved

{
  "event": "verification.checker",
  "timestamp": "2025-07-13T12:50:00Z",
  "trace_id": "trace_checker_approved_003",
  "VKYC_ref_id": "VYC9000002",
  "customer_ref": "CUST-002",
  "data": {
    "checked_by": "CHECKER001",
    "verified_at": "2025-07-13T12:49:55Z",
    "status": "APPROVED"
  }
}

200 OK — checker rejected

{
  "event": "verification.checker",
  "timestamp": "2025-07-13T12:50:00Z",
  "trace_id": "trace_checker_rejected_004",
  "VKYC_ref_id": "VYC9000002",
  "customer_ref": "CUST-002",
  "data": {
    "checked_by": "CHECKER002",
    "rejected_at": "2025-07-13T12:49:55Z",
    "rejection_reason": "id_mismatch",
    "rejection_remark": "PAN details do not match Aadhaar",
    "status": "REJECTED"
  }
}

200 OK — auditor approved

{
  "event": "verification.auditor",
  "timestamp": "2025-07-13T12:50:00Z",
  "trace_id": "trace_auditor_approved_005",
  "VKYC_ref_id": "VYC9000002",
  "customer_ref": "CUST-002",
  "data": {
    "audited_by": "AUDITOR001",
    "audited_at": "2025-07-13T12:49:55Z",
    "status": "APPROVED"
  }
}

200 OK — auditor rejected

{
  "event": "verification.auditor",
  "timestamp": "2025-07-13T12:50:00Z",
  "trace_id": "trace_auditor_rejected_006",
  "VKYC_ref_id": "VYC9000002",
  "customer_ref": "CUST-002",
  "data": {
    "audited_by": "AUDITOR002",
    "audited_at": "2025-07-13T12:49:55Z",
    "rejection_reason": "id_mismatch",
    "rejection_remark": "PAN details do not match Aadhaar",
    "status": "DECLINED"
  }
}

Parameter specification

Key	Type	Description
event	string	The last event recorded on the session.
timestamp	string	ISO 8601 UTC timestamp of the event.
trace_id	string	Unique request trace identifier — useful for debugging and logging.
VKYC_ref_id	string	PixDynamics-generated unique identifier for the VKYC session.
customer_ref	string	Client-provided reference ID.
data	object	Payload details — varies by event type.

Inside data

Field	Type	Used in event	Description
status	string	All	Current status, e.g. VERIFIED, REJECTED, APPROVED, DECLINED.
verified_by	string	vcip.application.verified_by_agent	Agent ID that verified the customer.
verified_at	string	vcip.application.verified_by_agent	Verification timestamp.
rejected_by	string	vcip.application.rejected_by_agent	Agent ID that rejected the customer.
rejected_at	string	vcip.application.rejected_by_agent	Rejection timestamp.
rejection_reason	string	Agent / checker / auditor rejection	Reason code for the rejection.
rejection_remark	string	Agent / checker / auditor rejection	Additional explanation of the rejection.
checked_by	string	verification.checker	Checker user / email that reviewed the application.
audited_by	string	verification.auditor	Auditor user / email that audited the application.
audited_at	string	verification.auditor	Timestamp of the audit.

HTTP response codes

HTTP code	Meaning	Usage scenario
200 OK	Success	VKYC status retrieved successfully.
400 Bad Request	Invalid request	Missing or invalid fields.
403 Forbidden	Access denied	The merchant is not authorised to access this VKYC session.
404 Not Found	Not found	No VKYC session found for the given identifiers.
429 Too Many Requests	Rate limit exceeded	Too many requests in a short time.
500 Internal Server Error	Server-side error	Unexpected error while processing the request.
503 Service Unavailable	Maintenance or overload	The VKYC backend service is temporarily unavailable.