openapi: 3.0.0 info: title: Universal Identity Extraction API version: 1.0.0 description: > **KYC-grade government ID and passport analysis** for PropTech background checks, Hospitality check-ins, and Age-Gated delivery applications. Accepts a government-issued ID or passport image — as a **base64 string** or a **public URL** — and uses **Google Gemini 2.5 Flash Lite** (vision) to: - **Extract personal information** — first name, last name, gender, and nationality with full transliteration support for non-Latin scripts (Arabic, Kanji, Cyrillic, Thai, Korean, Hindi, etc.). - **Parse MRZ codes** — extracts the complete Machine Readable Zone verbatim from Passports (TD3) and EU-style ID cards (TD1/TD2), preserving all `<` filler characters. - **Normalize addresses** — deeply parses addresses into `street`, `city`, `state_or_region`, and `postal_code` components. - **Standardize dates** — converts any date format (DD/MM/YY, DD MON YYYY, etc.) strictly to ISO 8601 `YYYY-MM-DD`. - **Compute exact age and expiry validation** — using Python's `datetime` module with UTC timezone awareness, guaranteeing mathematically precise results independent of the LLM. - **Surface quality flags** — legibility, glare/obstruction detection, and transliteration indicators. ### Key Verification Features | Feature | Detail | |---------|--------| | Multilingual OCR | Reads any language; transliterates non-Latin names to Latin alphabet | | MRZ Extraction | Full verbatim MRZ string for Passports and EU ID cards | | Address Normalization | Deep parse into street, city, state, postal_code | | Date Standardization | Any format → strict YYYY-MM-DD ISO 8601 | | Age Calculation | Python datetime math — never trust the LLM for arithmetic | | Expiry Check | UTC-aware comparison against today's date | | Minimum Age Gate | Configurable age threshold (default: 18) | | Quality Flags | Legibility, glare, obstruction, translation status | ### Use Cases - **PropTech** — Tenant background checks and identity verification before lease signing. - **Hospitality** — Automated check-in workflows that capture guest identity from a passport or national ID scan. - **Age-Gated Delivery** — Verify that a recipient meets the minimum age requirement at the point of delivery. - **KYC / AML Pipelines** — First-pass identity extraction before feeding to a full KYC provider. ### Cost & Safety Controls - **At least one** image source must be provided (`image_base64` or `image_url`). - URL-fetched images are capped at **5 MB** to prevent Lambda OOM and data-transfer abuse. - SSRF protection: `localhost`, `127.0.0.x`, `169.254.x`, and loopback addresses are blocked. - The LLM never computes age, expiry status, or minimum-age compliance — all three are injected by deterministic Python code after the model responds. - Gemini generation temperature is set to **0.1** for maximum extraction determinism. contact: name: Support license: name: Apache 2.0 servers: - url: https://7n75bbq4id.execute-api.us-east-1.amazonaws.com/prod description: Production API # REMOVED Backend Secrets. RapidAPI adds X-RapidAPI-Key automatically. security: [] tags: - name: Identity Extraction description: KYC-grade government ID and passport analysis with age and expiry validation paths: /vision/extract-identity-document: post: tags: - Identity Extraction summary: Extract structured data from a government ID or passport image description: > Accepts a government-issued ID or passport image via `image_base64` or `image_url` (at least one required). Uses Gemini 2.5 Flash Lite vision to perform multilingual OCR, extract personal info, parse MRZ codes, normalize addresses, and standardize dates. Python's `datetime` module then computes exact age and expiry validation. **Rules enforced by the AI**: - Non-Latin names (Arabic, Kanji, Cyrillic, etc.) are transliterated to the Latin alphabet; `is_translated` is set to `true`. - Dates in any format are strictly converted to `YYYY-MM-DD`. - The MRZ string is extracted verbatim with all `<` filler characters preserved. - Addresses are deeply parsed into `street`, `city`, `state_or_region`, `postal_code`. - Missing or unreadable fields are returned as `null` — never hallucinated. **Python-computed fields** (not LLM-generated): - `calculated_age` — exact age in whole years as of today (UTC). - `meets_minimum_age` — whether the person meets the `minimum_age_requirement`. - `is_expired` — whether the document's expiration date is in the past. operationId: extractIdentityDocument requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IdentityExtractionRequest' examples: passport_base64: summary: Passport via base64 value: image_base64: "/9j/4AAQSkZJRgABAQAAAQABAAD..." minimum_age_requirement: 18 id_via_url: summary: National ID via public URL value: image_url: "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" minimum_age_requirement: 21 delivery_age_check: summary: Age-gated delivery (21+ requirement) value: image_url: "https://example.com/id-scan.jpg" minimum_age_requirement: 21 responses: '200': description: Identity data successfully extracted and validated content: application/json: schema: $ref: '#/components/schemas/IdentityExtractionResponse' examples: passport_success: summary: UK Passport extraction value: status: success document_metadata: document_type: Passport issuing_country_iso2: GB document_number: "123456789" mrz_code: "P At least one of `image_base64` or `image_url` must be provided. If both are provided, `image_base64` takes precedence. Providing neither or an invalid base64 string will return a 400 error. properties: image_base64: type: string description: > Base64-encoded string of the ID/passport photo. Supports JPEG, PNG, GIF, and WebP formats. Either this or `image_url` must be provided, but not both. example: "/9j/4AAQSkZJRgABAQAAAQABAAD..." image_url: type: string format: uri description: > A public HTTPS/HTTP URL pointing to the ID/passport photo. The image will be fetched server-side and is subject to the 5 MB size limit. SSRF-protected — localhost and link-local addresses are blocked. Either this or `image_base64` must be provided, but not both. example: "https://example.com/passport-scan.jpg" minimum_age_requirement: type: integer minimum: 0 maximum: 150 default: 18 description: > The minimum age in whole years to validate against. Used to compute `meets_minimum_age` in the response. Defaults to 18. example: 21 IdentityExtractionResponse: type: object properties: status: type: string enum: [success] description: Always "success" on a 200 response. document_metadata: $ref: '#/components/schemas/DocumentMetadata' personal_info: $ref: '#/components/schemas/PersonalInfo' normalized_address: $ref: '#/components/schemas/NormalizedAddress' dates_and_validation: $ref: '#/components/schemas/DatesAndValidation' quality_flags: $ref: '#/components/schemas/QualityFlags' DocumentMetadata: type: object properties: document_type: type: string nullable: true enum: [Passport, "National ID", "Driver License", "Residence Permit", Other, null] description: The type of identity document detected. example: Passport issuing_country_iso2: type: string nullable: true minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code of the issuing authority. example: GB document_number: type: string nullable: true description: The document or passport number as printed on the document. example: "123456789" mrz_code: type: string nullable: true description: > The complete verbatim Machine Readable Zone string from the bottom of the document. For TD3 (Passport): two 44-character lines separated by `\n`. For TD1 (ID Card): three 30-character lines separated by `\n`. `null` if no MRZ is present or readable. example: "P Given name(s) in the Latin alphabet. Non-Latin names are transliterated; `is_translated` will be `true` in that case. example: John last_name: type: string nullable: true description: Family name in the Latin alphabet. example: Doe gender: type: string nullable: true enum: [M, F, X, null] description: Gender as indicated on the document. example: M nationality_iso2: type: string nullable: true minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code of the holder's nationality. example: GB NormalizedAddress: type: object description: > Deeply parsed address components. All fields are `null` for documents that do not carry an address (e.g., most passports). properties: full_address: type: string nullable: true description: The complete address as a single formatted line. example: "10 Downing St, London SW1A 2AA, UK" street: type: string nullable: true description: House number and street name. example: "10 Downing St" city: type: string nullable: true description: City or town. example: London state_or_region: type: string nullable: true description: State, province, county, emirate, etc. `null` if not applicable. example: null postal_code: type: string nullable: true description: ZIP code, postcode, or equivalent. `null` if not present. example: "SW1A 2AA" DatesAndValidation: type: object properties: date_of_birth_iso: type: string nullable: true format: date description: > Date of birth in strict ISO 8601 `YYYY-MM-DD` format. Converted from any date format printed on the document. `null` if unreadable. example: "1990-01-01" expiration_date_iso: type: string nullable: true format: date description: > Document expiration date in strict ISO 8601 `YYYY-MM-DD` format. `null` if unreadable or not present. example: "2030-01-01" calculated_age: type: integer nullable: true description: > Exact age in whole years computed by Python's `datetime` module as of today (UTC). `null` if `date_of_birth_iso` is unavailable or unparseable. example: 36 meets_minimum_age: type: boolean nullable: true description: > `true` if `calculated_age` ≥ `minimum_age_requirement`, `false` otherwise. `null` if `calculated_age` could not be determined. example: true is_expired: type: boolean nullable: true description: > `true` if the document's `expiration_date_iso` is strictly in the past (UTC today's date). `false` if valid. `null` if expiry date is unavailable. example: false QualityFlags: type: object properties: is_legible: type: boolean description: > `true` if the image is clear enough to read the key identity fields. `false` if too blurry, dark, or low-resolution. example: true glare_or_obstruction_detected: type: boolean description: > `true` if glare, shadows, a thumb, or physical damage partially obscures any readable field on the document. example: false is_translated: type: boolean description: > `true` if the document contained non-Latin script that was transliterated to produce the `first_name` and/or `last_name` values. example: false ErrorResponse: type: object properties: success: type: boolean example: false error: type: string description: Human-readable error message. example: "Either image_base64 or image_url is required"