> ## Documentation Index
> Fetch the complete documentation index at: https://docs.konnectnxt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Validation

> Validate document quality, detect document type, and check readability

## Overview

The Document Validation API performs comprehensive validation of document images to ensure they meet quality standards for verification workflows. It automatically detects document types, checks readability, identifies faces, determines document sides, and detects whether documents are scanned or original.

## Key Features

* **Automatic Document Type Detection**: Identifies PAN, Aadhaar, Passport, Driving License, Voter ID, and RC
* **Quality Assessment**: Evaluates document readability with confidence scores (0-100)
* **Face Detection**: Detects presence of faces in documents with photos
* **Side Detection**: Identifies front, back, or both sides of documents
* **Scan Detection**: Determines if document is scanned copy or original photo
* **Real-time Processing**: Typical processing time of 2-5 seconds

## Supported Document Types

| Document Type   | Code                  | Description                      |
| --------------- | --------------------- | -------------------------------- |
| PAN Card        | `ind_pan`             | Indian PAN Card                  |
| Aadhaar Card    | `ind_aadhaar`         | Indian Aadhaar Card (front/back) |
| Voter ID        | `ind_voter_id`        | Indian Voter ID (EPIC)           |
| Driving License | `ind_driving_license` | Indian Driving License           |
| Passport        | `ind_passport`        | Indian Passport                  |
| RC              | `ind_rc`              | Vehicle Registration Certificate |

## Technical Specifications

* **Maximum File Size**: 3MB
* **Supported Formats**: JPG, PNG, PDF
* **Request Timeout**: 50 seconds

## Required Information

* **document\_url**: Publicly accessible URL of the document (required)
* **doc\_type**: Expected document type (optional, improves accuracy)
* **detect\_face**: Enable face detection (default: true)
* **detect\_doc\_side**: Enable side detection (default: true)
* **check\_scan**: Enable scan detection (default: true)

## Response Fields

### Core Validation Results

| Field                    | Type    | Description                                            |
| ------------------------ | ------- | ------------------------------------------------------ |
| `detected_doc_type`      | string  | Auto-detected document type or "not\_detected"         |
| `is_readable`            | boolean | Whether document is readable and of sufficient quality |
| `readability_confidence` | integer | Quality score (0-100)                                  |
| `face_detected`          | boolean | Whether a face was found in the document               |
| `is_scanned`             | boolean | Whether document appears to be a scanned copy          |
| `detected_doc_side`      | string  | Document side: "front", "back", or "both" (if enabled) |

### Readability Confidence Scores

* **81-100**: Excellent quality - ideal for processing
* **61-80**: Acceptable quality - suitable for most use cases
* **31-60**: Poor quality - may have issues with OCR/verification
* **0-30**: Very poor quality - not recommended for processing


## OpenAPI

````yaml POST /v2/validate/document/
openapi: 3.0.0
info:
  title: KonnectNXT API Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://bgv.konnectnxt.com/api
    description: Production
  - url: https://testbgv.konnectnxt.com/api
    description: QA
security:
  - bearerAuth: []
paths:
  /v2/validate/document/:
    post:
      tags:
        - Validation
        - Document Validation
      summary: Validate Document Quality and Type
      description: >-
        Validates document images to identify document type, check readability,
        detect faces, identify document sides, and determine if documents are
        scanned or original. Supports Indian documents including PAN, Aadhaar,
        Passport, Driving License, and Voter ID.
      operationId: validateDocument
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentValidationRequest'
            examples:
              fullValidation:
                summary: Full validation with all features
                value:
                  document_url: https://example.com/documents/pan_card.jpg
                  doc_type: ind_pan
                  detect_face: true
                  detect_doc_side: true
                  check_scan: true
              minimalValidation:
                summary: Minimal validation (defaults applied)
                value:
                  document_url: https://example.com/documents/aadhaar.jpg
              passportValidation:
                summary: Passport with face detection only
                value:
                  document_url: https://example.com/documents/passport.jpg
                  doc_type: ind_passport
                  detect_face: true
                  detect_doc_side: false
                  check_scan: false
      responses:
        '200':
          description: Document validation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentValidationSuccessResponse'
              examples:
                panCardReadable:
                  summary: PAN Card - Readable with Face
                  value:
                    status: success
                    code: 200
                    message: Operation completed successfully
                    data:
                      detected_doc_type: ind_pan
                      detected_doc_side: front
                      is_readable: true
                      readability_confidence: 95
                      face_detected: true
                      is_scanned: false
                    credits_used: 5
                    credits_remaining: 95
                aadhaarFrontOnly:
                  summary: Aadhaar Front Side
                  value:
                    status: success
                    code: 200
                    message: Operation completed successfully
                    data:
                      detected_doc_type: ind_aadhaar
                      detected_doc_side: front
                      is_readable: true
                      readability_confidence: 88
                      face_detected: true
                      is_scanned: false
                    credits_used: 5
                    credits_remaining: 90
                poorQuality:
                  summary: Poor Quality Document
                  value:
                    status: success
                    code: 200
                    message: Operation completed successfully
                    data:
                      detected_doc_type: ind_driving_license
                      detected_doc_side: front
                      is_readable: false
                      readability_confidence: 35
                      face_detected: false
                      is_scanned: true
                    credits_used: 5
                    credits_remaining: 85
                notDetected:
                  summary: Document Type Not Detected
                  value:
                    status: success
                    code: 200
                    message: Operation completed successfully
                    data:
                      detected_doc_type: not_detected
                      is_readable: true
                      readability_confidence: 75
                      face_detected: false
                      is_scanned: false
                    credits_used: 5
                    credits_remaining: 80
        '400':
          description: Bad request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentValidationErrorResponse'
              examples:
                missingUrl:
                  summary: Missing document_url
                  value:
                    status: error
                    code: 400
                    message: >-
                      Malformed request - mandatory parameters missing or
                      invalid
                    error_code: BAD_REQUEST
                    credits_used: 0
                    credits_remaining: 100
                invalidUrl:
                  summary: Invalid URL format
                  value:
                    status: error
                    code: 400
                    message: document_url must be a valid HTTP/HTTPS URL
                    error_code: BAD_REQUEST
                    credits_used: 0
                    credits_remaining: 100
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentValidationErrorResponse'
              examples:
                payloadTooLarge:
                  summary: Document exceeds 3MB
                  value:
                    status: error
                    code: 413
                    message: Document payload too large (>3MB)
                    error_code: PAYLOAD_TOO_LARGE
                    credits_used: 0
                    credits_remaining: 100
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentValidationErrorResponse'
              examples:
                invalidImage:
                  summary: Invalid or corrupt image
                  value:
                    status: error
                    code: 422
                    message: Invalid document image (high/low resolution, or corrupt)
                    error_code: INVALID_IMAGE
                    credits_used: 0
                    credits_remaining: 100
                invalidPdf:
                  summary: Invalid or corrupt PDF
                  value:
                    status: error
                    code: 422
                    message: Invalid PDF document (high/low resolution, or corrupt)
                    error_code: INVALID_PDF
                    credits_used: 0
                    credits_remaining: 100
                invalidDocUrl:
                  summary: Document URL not accessible
                  value:
                    status: error
                    code: 422
                    message: Invalid document URL
                    error_code: INVALID_URL
                    credits_used: 0
                    credits_remaining: 100
                insufficientCredits:
                  summary: Not enough credits
                  value:
                    status: error
                    code: 422
                    message: Insufficient credits to process request
                    error_code: INSUFFICIENT_CREDITS
                    credits_used: 0
                    credits_remaining: 2.5
                invalidDocType:
                  summary: Invalid doc_type parameter
                  value:
                    status: error
                    code: 422
                    message: >-
                      Invalid doc_type. Must be one of: ind_pan, ind_aadhaar,
                      ind_voter_id, ind_driving_license, ind_passport
                    error_code: INVALID_FORMAT
                    credits_used: 0
                    credits_remaining: 100
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentValidationErrorResponse'
              examples:
                rateLimitExceeded:
                  summary: Too many requests
                  value:
                    status: error
                    code: 429
                    message: Rate limit reached - too many requests
                    error_code: RATE_LIMIT_EXCEEDED
                    credits_used: 0
                    credits_remaining: 100
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    DocumentValidationRequest:
      type: object
      required:
        - document_url
      properties:
        document_url:
          type: string
          format: uri
          pattern: ^https?://.+
          maxLength: 2048
          description: >-
            Publicly accessible URL of the document image to validate. Must use
            HTTP or HTTPS protocol. Document should not exceed 3MB.
          example: https://example.com/documents/pan_card.jpg
        doc_type:
          type: string
          enum:
            - ind_pan
            - ind_aadhaar
            - ind_voter_id
            - ind_driving_license
            - ind_passport
          description: >-
            Expected document type (optional). When provided, improves accuracy
            of validation. If omitted, system will auto-detect document type.
          example: ind_pan
        detect_face:
          type: boolean
          default: true
          description: >-
            Enable face detection in the document. Useful for documents that
            typically contain photos (Aadhaar, Passport, DL).
          example: true
        detect_doc_side:
          type: boolean
          default: true
          description: >-
            Enable document side detection (front/back/both). Helps identify
            which side of a two-sided document is provided.
          example: true
        check_scan:
          type: boolean
          default: true
          description: >-
            Enable scan detection to determine if document is a scanned copy.
            Useful for distinguishing between original photos and scanned
            documents.
          example: true
    DocumentValidationSuccessResponse:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/DocumentValidationData'
            credits_used:
              type: number
              format: float
              description: Number of credits consumed for this operation
              example: 5
              minimum: 0
            credits_remaining:
              type: number
              format: float
              description: Remaining credits in user account after this operation
              example: 95
              minimum: 0
    DocumentValidationErrorResponse:
      type: object
      required:
        - status
        - code
        - message
        - error_code
        - credits_used
        - credits_remaining
      properties:
        status:
          type: string
          enum:
            - error
          description: Response status indicator
          example: error
        code:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Human-readable error message
          example: Malformed request - mandatory parameters missing or invalid
        error_code:
          type: string
          enum:
            - BAD_REQUEST
            - UNAUTHORIZED
            - INVALID_CREDENTIALS
            - PAYLOAD_TOO_LARGE
            - INVALID_IMAGE
            - INVALID_PDF
            - INVALID_URL
            - INSUFFICIENT_CREDITS
            - RATE_LIMIT_EXCEEDED
            - PROVIDER_ERROR
            - TIMEOUT
            - INVALID_FORMAT
          description: Machine-readable error code for programmatic handling
          example: BAD_REQUEST
        credits_used:
          type: number
          format: float
          description: >-
            Credits consumed for this request (typically 0 for errors). Credits
            are only deducted on successful processing.
          example: 0
          minimum: 0
        credits_remaining:
          type: number
          format: float
          description: Remaining credits in user account
          example: 100
          minimum: 0
    APIBaseResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          $ref: '#/components/schemas/APIStatus'
        code:
          $ref: '#/components/schemas/HTTPCode'
        message:
          $ref: '#/components/schemas/APIMessage'
    DocumentValidationData:
      type: object
      required:
        - detected_doc_type
        - is_readable
        - readability_confidence
        - face_detected
        - is_scanned
      properties:
        detected_doc_type:
          type: string
          enum:
            - ind_pan
            - ind_aadhaar
            - ind_voter_id
            - ind_driving_license
            - ind_passport
            - ind_rc
            - not_detected
          description: >-
            Automatically detected document type. Returns 'not_detected' if type
            cannot be determined.
          example: ind_pan
        detected_doc_side:
          type: string
          enum:
            - front
            - back
            - both
          description: >-
            Detected side of the document (only included if detect_doc_side is
            enabled). Helps identify front, back, or both sides of multi-sided
            documents.
          example: front
        is_readable:
          type: boolean
          description: >-
            Indicates whether the document image is readable and of sufficient
            quality. Based on resolution, clarity, and noise levels.
          example: true
        readability_confidence:
          type: integer
          minimum: 0
          maximum: 100
          description: >-
            Confidence score for document readability (0-100). Higher scores
            indicate better quality. 0-30: Very poor, 31-60: Poor, 61-80:
            Acceptable, 81-100: Good to excellent.
          example: 95
        face_detected:
          type: boolean
          description: >-
            Indicates whether a face was detected in the document. Only
            applicable when detect_face is enabled. Useful for documents with
            photos (Aadhaar, Passport, DL).
          example: true
        is_scanned:
          type: boolean
          description: >-
            Indicates whether the document appears to be a scanned copy. Helps
            distinguish between original photos and scanned documents. Only
            applicable when check_scan is enabled.
          example: false
    Error:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
    APIErrorData:
      type: object
      properties:
        data:
          type: object
          nullable: true
          example: null
    APIStatus:
      type: string
      enum:
        - success
        - error
      description: Overall status of the API
    HTTPCode:
      type: integer
      description: HTTP status code
      example: 400
    APIMessage:
      type: string
      description: Description of the response or error
      example: Invalid request parameters
  responses:
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Missing Token:
              summary: Bearer token is missing or invalid.
              value:
                status: error
                code: 401
                message: Bearer token is missing or invalid.
                data: null
            Incorrect Token Format:
              summary: Token format is incorrect
              value:
                status: error
                code: 401
                message: Token format is incorrect
                data: null
            No Admin Found:
              summary: No admin found for this request
              value:
                status: error
                code: 401
                message: No admin user found for this organization
                data: null
            Invalid API Key:
              summary: Invalid API Key
              value:
                status: error
                code: 401
                message: Invalid API key (organization ID)
                data: null
            User not Found:
              summary: User not found
              value:
                status: error
                code: 401
                message: User not found.
                data: null
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Token Revoked:
              summary: Token access has been Revoked, Contact Support.
              value:
                status: error
                code: 403
                message: Token access has been Revoked, Contact Support.
                data: null
            Token Inactive:
              summary: Token is Inactive, Contact Support.
              value:
                status: error
                code: 403
                message: Token is Inactive, Contact Support.
                data: null
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Internal Server Error:
              summary: Internal Server Error.
              value:
                status: error
                code: 500
                message: Internal Server Error.
                data: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key issued by KonnectNXT. Pass as `Authorization: Bearer
        <your_api_key>`.

````