KYC API Request

📤 Ditto ID KYC API Request Format

This section describes the request payload that Ditto ID sends to your enterprise backend when triggering a KYC submission. The backend must expose a POST endpoint to receive this payload.

🔗 Endpoint Specification

POST /kyc
Authorization: Bearer <token> OR Basic <credentials>
Content-Type: application/json

Your server must support HTTPS and validate the authorization headers if configured.

🧩 Sample JSON Payload

{
  "request_info": {
    "user_id": "testuser1",
    "app_id": "15bdab25-f23c-49ba-bdab-25f23c49baf1",
    "requester_id": "9c1c0236-3152-49f1-9bff-d02f6123fae6"
  },
  "kyc_info": {
    "liveness_check": {
      "video": {
        "autocapture_result": {
          "selfie_image": "<Base64 Image>"
        },
        "liveness_result": {
          "score": 100
        }
      }
    },
    "face_matcher_result": {
      "score": 0.0002,
      "score_percent": 0
    },
    "document": {
      "version": "3.0",
      "document_info": {
        "document_type": ["Identity Card"],
        "document_names": ["Latvia - ID Card (2012)"],
        "field_sources": ["M", "V"],
        "field_locales": {
          "0": "Latin"
        },
        "field_list": [
          "Document number",
          "Date of expiry",
          "Given name"
        ],
        "document_images": {
          "front_page": "<Base64>",
          "portrait_image": "<Base64>"
        }
      },
      "document_status": {
        "error_list": ["Expired Document"],
        "is_nfc_document": true,
        "nfc_scan_status": "NFC SCAN UNSUPPORTED BY DEVICE",
        "overall_document_status": "ERROR"
      },
      "identity_data": {
        "Document number": "PA9992592",
        "Given name": "John"
      },
      "identity_data_details": {
        "0": [
          {
            "field_name": "Given name",
            "field_details": {
              "field_value": "John",
              "field_status": "OK",
              "field_source_and_values": {
                "M": "John"
              }
            }
          }
        ]
      },
      "raw_data" :<DocScanData_FromRelIdSdk Super Set Object>,
    }
  }
}

🧾 Request Field Descriptions

📂 request\_info

Field	Type	Description
`user_id`	string	Ditto ID user ID, usually an email address or phone number.
`app_id`	string	Identifier for the mobile app used during user onboarding.
`requester_id`	string	Unique identifier for this KYC request, used for tracking and auditing.

📦 kyc\_info

The kyc_info object contains identity verification data collected from the Ditto ID SDK.

📄 document

| Field                                                                        | Type   | Description                                              |
| ---------------------------------------------------------------------------- | ------ | -------------------------------------------------------- |
| `version`                                                                    | string | JSON format version (e.g., "3.0")                        |
| [`document_info`](document-fields#/-document_info--detailed-field-reference) | object | Metadata, field list, and images from the document       |
| [ `document_status`](document-fields#/-api-documentation-document_status)    | object | Validation results including NFC and authenticity checks |
| `identity_data`                                                              | object | Simplified field-value pairs (e.g., name, DOB)           |
| [`identity_data_details`](document-fields#/-api-documentation-identity_data-and-identity_data_details)                                                      | object | Locale-wise structured field mapping                     |
| `raw_data`                                                                   | object | Complete extracted data set (only if enabled in config)  |

🎥 liveness\_check

| Field                                   | Type   | Description                                         |
| --------------------------------------- | ------ | --------------------------------------------------- |
| `video.autocapture_result.selfie_image` | string | Base64-encoded selfie image                         |
| `video.liveness_result.score`           | int    | Score (0–100) indicating confidence of live capture |

🧠 face\_matcher\_result

| Field           | Type  | Description                                      |
| --------------- | ----- | ------------------------------------------------ |
| `score`         | float | Raw similarity score between selfie and portrait |
| `score_percent` | int   | Biometric match score as a percentage (0–100)    |