Integration Guide & API Reference

Welcome to the official MYETV Identity Provider documentation. Integrate our adaptive Frontend SDK or direct backend HTTP endpoints to verify identities, enforce anti-forgery forensics, and extract structured data from Electronic Identity Cards (CIE / eID), ICAO Passports, Driver's Licenses, and Residence Permits worldwide.

2. API Keys & Granular Security Rules

To authenticate requests, create an API Key from your Developer Dashboard. Each key carries its own extraction schema, biometric settings, and security enforcement rules:

• Requested vs. Strict Required Fields: Choose which fields the Vision AI extracts in the JSON response, and mark essential fields that must be readable or fail with HTTP 422.
• MRZ & Barcode/PDF417 Validation: Configure MRZ and 2D Barcode checks as Disabled, Opportunistic (validate when present), or Required (reject documents missing MRZ/barcode). When MRZ Required is active, the capture widget automatically disables non-MRZ documents (such as driver's licenses).
• IP Whitelisting Restriction: Locks API calls exclusively to your server's static IP address.
• Domain Restriction (CORS): Restricts capture widget iframe embedding strictly to your authorized domain or subdomains.
• Auto-Expiration Policy: Optionally schedules an automatic expiration timestamp for the key.

Allowed Issuing Countries

By default, new API Keys accept documents from All Countries Enabled. From the creation or edit modal in your dashboard, you can restrict an API Key to a custom subset of issuing countries:

• Widget UI Filtering: Only the enabled countries appear in the capture widget's country selector.
• Mobile Handoff Validation: The mobile handoff service rejects QR handoff requests for countries outside the key's whitelist.
• Backend Pre-AI & Post-AI Enforcement: The verification endpoint checks both the declared document_country parameter and the actual country_of_issuance / MRZ issuing state extracted from the document image, returning 403 country_not_allowed if unauthorized.

Editing Active API Keys

Active API Keys can be reconfigured at any time directly from the dashboard via the Edit button (next to Test UI and Revoke) without regenerating credentials or breaking live integrations. Revoked or banned keys are read-only.

Forensic Checks & Biometrics

• EXIF Manipulation & Error Level Analysis (ELA): Detects editing software traces (Photoshop, GIMP, Canva, etc.) and generates an ELA map to spot digitally altered text.
• Screen / Moiré & Anti-Handwritten Defenses: Rejects photos of computer/phone monitors, plain paper sheets, specimens/samples, glued replacement photos, and handwritten documents.
• Enable Active Liveness Detection: Guides users through real-time head rotation checks (with mobile facial landmark tracking and haptic feedback) before capturing the selfie.
• Enable Face Matching: Compares the user's live selfie against the portrait printed on the identity document, returning face_match_passed and face_match_confidence (0–100).
• Age Verification Only Mode: Strips personal identity attributes from the response, returning strictly years_old, fraud indicators, and optional face match results for data minimization.

3. Adaptive Capture Widget & Document Catalog

Before opening the camera, file upload, or smartphone handoff QR code, the capture widget guides the user through selecting their Issuing Country and Document Type. Based on this choice, both PC webcam and smartphone scanners adapt automatically:

• ID-1 Cards (1.586 : 1): Electronic National IDs, Driver's Licenses, Residence Permits — requires Front & Back captures.
• ID-3 Passports (1.42 : 1): ICAO 9303 Bio-Data Page — switches to a taller passport mask with a dedicated Photo and Bottom MRZ Zone alignment guide, and requires 1 photo only (automatically skipping the Back capture step).
• Legacy ID-2 Cards (1.42 : 1): Where supported (e.g., French legacy laminated CNI with MRZ) — adapts mask proportions and captures Front & Back.

Automatic Country Detection Priority

When the capture widget loads, it selects the initial country automatically using the following fallback chain (constrained to the API Key's allowed countries):

1. Explicit Parameter: defaultCountry in MyETVIdentity.init() (or query parameter override).
2. Browser Locale Region: Extracted from browser language preferences (e.g., it-IT → IT, en-US → US, fr-FR → FR).
3. Geolocation Header Fallback: Server-side IP country detection when the browser locale lacks a region subtag.
4. Catalog Fallback: OTHER (if enabled on the API Key) or the first enabled country in the catalog.

Supported Countries & Documents

For countries whose domestic IDs use non-Latin scripts exclusively without English transliteration, the catalog prioritizes International ICAO Passports (which universally include Latin fields and an ASCII MRZ) to guarantee high OCR accuracy.

4. Server Configuration & Browser Permissions

Because the capture widget runs inside a cross-origin <iframe>, your host website must allow camera access delegation via the Permissions-Policy HTTP header (e.g., in Apache .htaccess or Nginx):

# Allow iframe camera access for the Identity Provider domain
Header set Permissions-Policy "camera=(self \"https://identityprovider.myetv.tv\")"

5. Integration Methods

<!-- 1. Include the SDK -->
<script src="https://identityprovider.myetv.tv/sdk/mip_sdk.js"></script>

<!-- 2. Create a container for the widget -->
<div id="identity-verification-container" style="width:100%; min-height:600px;"></div>

<script>
    // Define your secure backend proxy endpoint
    var processUrl = "https://[YOURDOMAINURL]/process_identity_verification.php";

    // 3. Initialize the SDK
    MyETVIdentity.init({
        apiKey: 'myetv_live_YOUR_API_KEY', // Required: validates domain, country list & biometrics
        defaultCountry: 'IT',              // Optional: pre-selects country (auto-detected if omitted)
        backendEndpoint: processUrl,
        
        onSuccess: function(result) {
            console.log("Verification Complete!", result);
            alert("Success: " + (result.message || "Verified!"));
        },
        onError: function(error) {
            console.error("Verification Failed:", error);
            alert("Error: " + (error.details || error.message));
        }
    });

    // 4. Mount the widget
    MyETVIdentity.mount('identity-verification-container');
</script>

<?php
// process_identity_verification.php (Your Backend Proxy Example)
session_start();
$apiKey    = 'myetv_live_YOUR_API_KEY';
$apiSecret = 'YOUR_API_SECRET';
$endpoint  = 'https://identityprovider.myetv.tv/api/v1/verify.php';

// Ensure primary document image has been uploaded successfully
if (!isset($_FILES['document_front']) || $_FILES['document_front']['error'] !== UPLOAD_ERR_OK) {
    http_response_code(400);
    echo json_encode(['status' => 'error', 'error' => 'missing_front_document']);
    exit;
}

$postFields = [
    'document_front' => new CURLFile(
        $_FILES['document_front']['tmp_name'],
        mime_content_type($_FILES['document_front']['tmp_name']),
        $_FILES['document_front']['name']
    )
];

if (isset($_FILES['document_back']) && $_FILES['document_back']['error'] === UPLOAD_ERR_OK) {
    $postFields['document_back'] = new CURLFile(
        $_FILES['document_back']['tmp_name'],
        mime_content_type($_FILES['document_back']['tmp_name']),
        $_FILES['document_back']['name']
    );
}

if (isset($_FILES['selfie_image']) && $_FILES['selfie_image']['error'] === UPLOAD_ERR_OK) {
    $postFields['selfie_image'] = new CURLFile(
        $_FILES['selfie_image']['tmp_name'],
        mime_content_type($_FILES['selfie_image']['tmp_name']),
        $_FILES['selfie_image']['name']
    );
}

// Forward optional country and document type metadata selected in the widget
if (!empty($_POST['document_country'])) {
    $postFields['document_country'] = $_POST['document_country'];
}
if (!empty($_POST['document_type'])) {
    $postFields['document_type'] = $_POST['document_type'];
}

// Initialize cURL with extended timeout (120s)
$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: ' . $apiKey,
    'X-API-SECRET: ' . $apiSecret
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    
    // TODO: Store verified attributes securely in your database
    echo json_encode([
        'status'  => 'success',
        'message' => 'Identity verified and data extracted successfully.',
        'data'    => $data
    ]);
} else {
    http_response_code($httpCode ?: 500);
    echo $response;
}
?>

# Example 1: 2-Sided Electronic ID Card (with Face Match)
curl -X POST https://identityprovider.myetv.tv/api/v1/verify.php \
  -H "X-API-KEY: myetv_live_YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -F "document_country=IT" \
  -F "document_type=it_cie" \
  -F "document_front=@/path/to/cie_front.jpg" \
  -F "document_back=@/path/to/cie_back.jpg" \
  -F "selfie_image=@/path/to/selfie.jpg"

# Example 2: 1-Sided Passport Bio-Data Page
curl -X POST https://identityprovider.myetv.tv/api/v1/verify.php \
  -H "X-API-KEY: myetv_live_YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -F "document_country=GB" \
  -F "document_type=passport" \
  -F "document_front=@/path/to/passport_biodata.jpg"

6. JSON Response Structure & Extracted Fields

On success (HTTP 200 OK), the verification endpoint returns a JSON object containing the fields configured on your API Key, normalized ISO dates (YYYY-MM-DD), computed age (years_old), and forensic flags.

{
  "document_type": "IDENTITY_CARD",
  "first_name": "Mario",
  "last_name": "Rossi",
  "date_of_birth": "1995-03-23",
  "place_of_birth": "Roma (RM)",
  "gender": "M",
  "nationality": "ITA",
  "document_number": "CA12345XY",
  "country_of_issuance": "ITA",
  "address": "Via Roma 1, 00100 Roma (RM)",
  "fiscal_code": "RSSMRA85R23H501W",
  "expiration_date": "2030-05-15",
  "mrz_code": "C<ITACA12345XY1<<<<<<<<<<<<<<<9503235M3005158ITA<<<<<<<<<<<4ROSSI<<MARIO<<<<<<<<<<<<<<<<<",
  "is_digitally_forged": false,
  "is_screen_photo": false,
  "face_match_confidence": 96,
  "face_match_passed": true,
  "error": null,
  "years_old": 31
}

Extracted Fields Reference

Age Verification Only Mode Response (JSON)

When Age Verification Only is enabled on the API Key, personal fields are omitted:

{
  "years_old": 31,
  "is_digitally_forged": false,
  "is_screen_photo": false,
  "face_match_passed": true,
  "face_match_confidence": 96
}

How to Parse Extracted Fields in PHP

<?php
$resultData = json_decode($apiResponseString, true);

if (is_array($resultData) && empty($resultData['error'])) {
    $firstName      = $resultData['first_name'] ?? '';
    $lastName       = $resultData['last_name'] ?? '';
    $dateOfBirth    = $resultData['date_of_birth'] ?? '';
    $placeOfBirth   = $resultData['place_of_birth'] ?? '';
    $documentNumber = $resultData['document_number'] ?? '';
    $fiscalCode     = $resultData['fiscal_code'] ?? '';
    $yearsOld       = $resultData['years_old'] ?? null;

    if (!empty($documentNumber)) {
        // Save verified user data securely
    }
}
?>

7. HTTP Error Codes & Troubleshooting