---
title: "OCR Service — Consumer Guide"
slug: ocr-consumer-guide
section: Integrations
status: stable
description: "Reference guide for services consuming the private Globus OCR microservice."
last-updated: 2026-07-07
---

# OCR Service — Consumer Guide

# Globus OCR Service — Consumer Guide

Reference guide for services consuming the private Globus OCR microservice. Covers all endpoints, request/response shapes, error codes, and Globus field-mapping conventions.

## Overview

The Globus OCR service is a private microservice that extracts text and structured fields from identity and general documents using GCP Document AI. Identity fields (passport, national ID, visa) are parsed deterministically from the ICAO 9303 machine-readable zone (MRZ), with a best-effort fallback to the printed visual zone (VIZ) for fields the MRZ omits or fails to read. A general raw-text endpoint serves any other document (e.g. criminal-background records). There is no public-AI fallback — on failure the service returns a structured error.

> **Reachable in-cluster only.**
>
> The base URL http://ocr-service.globus-development.svc.cluster.local:8080 is a ClusterIP address and is NOT reachable from outside the GKE cluster (local/Replit environments cannot call it directly). Use this guide to map your integration and expect these exact shapes when calling from an in-cluster service (e.g. the Globus Hub) or via kubectl port-forward svc/ocr-service 8080:8080.

## API Endpoints

| Environment | Base URL |
| --- | --- |
| Development (in-cluster) | http://ocr-service.globus-development.svc.cluster.local:8080 |

## Authentication

All endpoints except /health require a bearer token.

- Obtain the token: GCP secret globus- -internal-ocr-api-key (dev: globus-development-internal-ocr-api-key), surfaced to callers as INTERNAL_OCR_API_KEY.

- Send it in the header: Authorization: Bearer .

> **Auth errors.**
>
> A missing or invalid token returns 401/403. The token is shared per environment.

## Request Parameters

Common to all POST endpoints:

| Parameter | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| document_base64 | string | Yes | Base64-encoded file content (image or PDF). | "JVBERi0..." |
| mime_type | string | Yes | One of image/jpeg, image/png, application/pdf. | "application/pdf" |
| enable_language_detection | boolean | No | Detect languages (default true). | true |
| document_type | string | /identity only | passport \| id_card \| visa (default passport). | "id_card" |

## Endpoints

### POST /api/v1/ocr/passport

Passport OCR (MRZ TD3 + visual zone) with MRZ→VIZ field-level fallback.

### POST /api/v1/ocr/identity

Same as /passport but for any MRZ-bearing identity document; add document_type (passport | id_card | visa). Parses TD3 / TD1 / TD2 / MRV. Response is the same OCRResponse shape.

### POST /api/v1/ocr/text

General raw-text OCR for any/unstructured document (no field parsing).

### GET /health

Returns . No auth required.

## Response Fields

data (identity endpoints)

| Field | Source | Notes |
| --- | --- | --- |
| given_names, surname, nationality, passport_number, date_of_birth, expiry_date, issuing_country | MRZ (fallback: VIZ) | Dates YYYY-MM-DD; nationality/issuing_country ISO-3. |
| place_of_birth, date_of_issue | Visual zone only | Never encoded in the MRZ. |

metadata

| Field | Description |
| --- | --- |
| mrz_found | Whether the MRZ parsed (identity endpoints). |
| field_sources | Per-field origin: mrz or viz. |
| document_type | passport \| id_card \| visa \| general. |
| detected_languages, processor_version, execution_time_ms, preprocessing | Processing metadata. |

Confidence: MRZ fields 1.0 (0.9 if check digits fail), VIZ-fallback fields 0.6, absent fields 0.0.

## Response Codes

Successful

Recommended action: none.

| Code | Description |
| --- | --- |
| 200 | Success. Fields may be empty if nothing could be parsed. |

Client error

Recommended action: fix the request; do not retry unchanged.

| Code | Description |
| --- | --- |
| 400 | Invalid base64, empty document, >20 MB, unsupported mime, or preprocessing_output_invalid. |
| 401 / 403 | Missing or invalid bearer token. |
| 422 | Validation error (e.g. invalid document_type). |

Server / capacity

Recommended action: retry 503 after a short delay; 500 has no fallback (degrade to manual entry).

| Code | Description |
| --- | --- |
| 500 | ocr_processing_failed — Document AI error. |
| 503 | quota_exhausted — retry shortly. |

## Document Type Support

| Document | Support |
| --- | --- |
| Passport | MRZ TD3 + VIZ fallback ✅ |
| National ID card | MRZ TD1/TD2 ✅ |
| Visa | MRZ MRV-A/B ✅ |
| Driver's license | Raw text via /api/v1/ocr/text (no structured parsing yet) |
| Birth certificate | Raw text via /api/v1/ocr/text |
| Anything else | Raw text via /api/v1/ocr/text |

## Translating Visual-Zone Values

> **OCR does not translate.**
>
> VIZ-derived values (place_of_birth, date_of_issue, and any field whose field_sources entry is viz) are returned verbatim in the document's printed language/script. The OCR service does not translate. Consumers (e.g. Globus) must translate as needed — e.g. route them through the translation service — before display. Country fields are mapped to ISO-3 where recognised; unrecognised values pass through verbatim.

## Mapping into Globus

Globus consumes /api/v1/ocr/passport via server/services/gcpDocumentAiAdapter.ts (extractPassportViaOcr): it Title-Cases names, resolves nationality/issuing_country codes to a country name + ISO alpha-2, and coerces confidence to binary ( >= 0.5 = present). place_of_birth/ date_of_issue already map. /api/v1/ocr/identity and /api/v1/ocr/text are new adapter functions/capabilities to add on the Globus side.

Updated 2026-07-07