Guides

Response Format

Understand the standard response structure returned by all Deepvue APIs, including success responses, error responses, and common fields.

Overview

All Deepvue APIs return JSON responses with a consistent structure. Understanding this format helps you parse responses reliably across all endpoints.

Success response

Every successful API response includes these standard fields:

{
  "code": 200,
  "timestamp": 1738040933033,
  "transaction_id": "ece94d5e2749482faa10184962e9e34a",
  "data": {
    // Endpoint-specific response data
  }
}

codeinteger

Required

HTTP status code mirrored in the response body. Always 200 for successful requests.

timestampinteger

Required

Unix timestamp (in milliseconds) indicating when the response was generated.

transaction_idstring

Required

Unique identifier for this API call. Use this for debugging, support requests, and audit trails.

dataobject

Required

The verification result or resource data. Structure varies by endpoint — refer to the specific API reference for field details.

Error response

Error responses return a detail field with a human-readable message:

{
  "detail": "Not authenticated"
}

detailstring

Required

Human-readable error message describing what went wrong. See Error Handling for all error codes and messages.

Error responses do not include code, timestamp, or transaction_id fields. Use the HTTP status code from the response header to determine the error type.

Example responses by category

{
  "code": 200,
  "timestamp": 1738040933033,
  "transaction_id": "ece94d5e2749482faa10184962e9e34a",
  "data": {
    "@entity": "pan",
    "pan": "AAAPT0002F",
    "full_name": "RATAN NAVAL TATA",
    "status": "VALID",
    "category": "Individual",
    "name_information": {
      "pan_name_cleaned": "Ratan Naval Tata"
    }
  }
}

Parsing best practices

Always check code first — Verify the response code is 200 before accessing the data field.
Store transaction_id — Log this value for every request. It's required when contacting support and useful for audit trails.
Handle missing fields gracefully — Not all fields are guaranteed in every response. Some fields may be null or absent depending on the data source.
Use timestamp for ordering — When processing multiple responses, use the timestamp field to determine the order of events.
Don't hardcode field names — The data object structure varies by endpoint. Parse responses based on the specific API you're calling.

Was this page helpful?

Built with Documentation.AI

Last updated 1 day ago