Skip to main content
Our ID Verification process performs comprehensive validation of identity documents, extracting and verifying key information. This guide explains the structure and contents of a verification report.

​
Report Structure

The verification report is returned as a JSON object containing a id_verification object with the following key sections:
  • ID Verification Status: Overall session status and specific verification results
  • Document Details: Type and identifiers of the verified document
  • Personal Information: Extracted biographical data
  • Document Media: URLs to captured images and videos
  • Address Information: Structured location data
  • Verification Metadata: Additional verification details and timestamps

​
Core Response Fields

interface ImageQualityScore {
  focus_score: number;           // 0-100, sharpness (top-10% local Laplacian variance, robust to uniform backgrounds)
  brightness_score: number;      // 0-100, penalizes too dark or overexposed images
  brightness_issue: 'ok' | 'too_dark' | 'too_bright'; // indicates direction when brightness is low
  is_document_fully_visible: boolean | null; // true if all document corners are inside the frame
  resolution_score: number;      // 0-100, based on total pixel count
  overall_score: number;         // 0-100, weighted composite (focus 45%, brightness 30%, resolution 25%)
}

interface DocumentVerificationResponse {
  id_verification: {
    status: 'Approved' | 'Declined' | 'In Review' | 'Expired' | 'Not Finished';
    document_type: 'Passport' | 'Identity Card' | "Driver's License" | 'Residence Permit' | null;  // Nullable
    document_number: string;
    personal_number: string;
    portrait_image: string;        // Temporary URL
    front_image: string;          // Temporary URL
    front_video: string;         // Temporary URL
    back_image: string;          // Temporary URL
    back_video: string;          // Temporary URL
    full_front_image: string;     // Temporary URL
    full_back_image: string;     // Temporary URL
    date_of_birth: string;         // YYYY-MM-DD
    age: number;
    expiration_date: string;       // YYYY-MM-DD
    date_of_issue: string;        // YYYY-MM-DD
    issuing_state: string;         // ISO 3166-1 alpha-3
    issuing_state_name: string;
    first_name: string;
    last_name: string;
    full_name: string;
    gender: 'M' | 'F' | 'U';
    address: string;
    formatted_address: string;
    place_of_birth: string;
    marital_status: 'SINGLE' | 'MARRIED' | 'DIVORCED' | 'WIDOWED' | 'UNKNOWN';
    nationality: string;           // ISO 3166-1 alpha-3
    front_image_quality_score: ImageQualityScore | null;
    back_image_quality_score: ImageQualityScore | null;
    extra_fields: {
      dl_categories: string[];
      blood_group: string;
    },
    parsed_address: {
      address_type: string;
      street_1: string;
      street_2: string;
      city: string;
      region: string;
      postal_code: string;
      raw_results: {
        geometry: {
          location: {
            lat: number;
            lng: number;
          };
          location_type: string;
          viewport: {
            northeast: {
              lat: number;
              lng: number;
            };
            southwest: {
              lat: number;
              lng: number;
            };
          };
        };
      };
    };
    extra_files: string[];
    warnings: {
      risk: string;
      additional_data: string | null;
      log_type: 'information' | 'warning' | 'error';
      short_description: string;
      long_description: string;
    }[];
  }
}

​
Sample JSON Response

{
  "id_verification": {
    "status": "Approved",
    "document_type": "Identity Card",
    "document_number": "CAA000000",
    "personal_number": "99999999R",
    "portrait_image": "https://example.com/portrait.jpg",
    "front_image": "https://example.com/front.jpg",
    "front_video": "https://example.com/front.mp4",
    "back_image": "https://example.com/back.jpg",
    "back_video": "https://example.com/back.mp4",
    "full_front_image": "https://example.com/full_front.jpg",
    "full_back_image": "https://example.com/full_back.jpg",
    "date_of_birth": "1980-01-01",
    "age": 45,
    "expiration_date": "2031-06-02",
    "date_of_issue": "2021-06-02",
    "issuing_state": "ESP",
    "issuing_state_name": "Spain",
    "first_name": "Carmen",
    "last_name": "Española Española",
    "full_name": "Carmen Española Española",
    "gender": "F",
    "address": "Avda de Madrid 34, Madrid, Madrid",
    "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
    "place_of_birth": "Madrid",
    "marital_status": "Single",
    "nationality": "ESP",
    "extra_fields": {
      "dl_categories": [],
      "blood_group": null
    },
    "parsed_address": {
      "address_type": "Avda",
      "city": "Madrid",
      "label": "Spain ID Card Address",
      "region": "Madrid",
      "street_1": "Avda de Madrid 34",
      "street_2": null,
      "postal_code": "28822",
      "raw_results": {
        "geometry": {
          "location": {
            "lat": 37.4222804,
            "lng": -122.0843428
          },
          "location_type": "ROOFTOP",
          "viewport": {
            "northeast": {
              "lat": 37.4237349802915,
              "lng": -122.083183169709
            },
            "southwest": {
              "lat": 37.4210370197085,
              "lng": -122.085881130292
            }
          }
        },
      },
    },
    "front_image_quality_score": {
      "focus_score": 85.3,
      "brightness_score": 92.1,
      "brightness_issue": "ok",
      "is_document_fully_visible": true,
      "resolution_score": 72.4,
      "overall_score": 88.7
    },
    "back_image_quality_score": {
      "focus_score": 79.1,
      "brightness_score": 90.5,
      "brightness_issue": "ok",
      "is_document_fully_visible": true,
      "resolution_score": 72.4,
      "overall_score": 85.2
    },
    "extra_files": [
      "https://example.com/extra_id_verification.jpg",
    ],
    "warnings": [
      {
        "risk": "QR_NOT_DETECTED",
        "additional_data": null,
        "log_type": "information",
        "short_description": "QR not detected",
        "long_description": "The system couldn't find or read the QR code on the document, which is necessary for document verification. This could be due to poor image quality or an unsupported document type.",
      }
    ],
  },
}
For more information about potential warnings during the ID verification process, check our ID Verification Warnings guide.

​
Image Quality Scores

Each document side receives a quality assessment returned as front_image_quality_score and back_image_quality_score. These scores help you evaluate whether the captured images are suitable for reliable document verification. All sub-scores range from 0 (worst) to 100 (best).
FieldTypeWhat it measures
focus_scorenumber (0-100)Sharpness of the image using top-10% local Laplacian variance, robust to documents with large uniform backgrounds. Weight: 45%
brightness_scorenumber (0-100)How well-lit the image is. Penalizes images that are too dark or overexposed. Weight: 30%
brightness_issue"ok" | "too_dark" | "too_bright"Indicates the direction of the brightness problem when brightness_score is low.
resolution_scorenumber (0-100)Effective resolution based on the total pixel count of the uploaded image. Weight: 25%
is_document_fully_visibleboolean or nulltrue if all four corners of the document are fully visible inside the image frame, false if any corner is cut off. null when corner coordinates are unavailable.
overall_scorenumber (0-100)Weighted average of focus (45%), brightness (30%), and resolution (25%).
Use the overall_score as a quick indicator of image quality. Scores above 70 generally indicate a good capture suitable for reliable verification.

​
Security Note

The URLs provided for document images are temporary and expire after 60 minutes for enhanced security. Ensure these URLs are handled with appropriate security measures and are not shared publicly. Typically, your application will only require the verification status and essential personal details. As a best practice, minimize the amount of data stored on your servers.