{
  "openapi": "3.0.3",
  "info": {
    "title": "PicToText OCR API",
    "description": "Structured OCR for identity documents. Send one image of a national ID card, passport, or driver's license plus a country-specific `documentType`, and get clean structured JSON back.\n\n- **30+ countries, 44 document types** — national ID cards, passports, and driver's licenses.\n- **Native-script extraction** — Latin, Chinese, Thai, and Arabic — returning names in the document's own script, plus a Latin form when the document prints one.\n- **Passports**: ICAO 9303 TD3 MRZ extraction for booklet-style passports.\n- **Per-country fields**: each document returns the fields it actually prints, with dates normalized to ISO 8601.\n- **New accounts include 100 free API calls** — no card required.\n\nBuilt for KYC and identity-verification workflows: onboarding, eKYC, marketplace verification, age and identity checks, cross-border compliance.",
    "version": "1.0.0",
    "contact": {
      "name": "PicToText",
      "url": "https://pictotext.io/about"
    },
    "termsOfService": "https://pictotext.io/terms"
  },
  "servers": [
    {
      "url": "https://pictotext.io",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Full documentation: quickstart, field references, and the complete per-country document list",
    "url": "https://pictotext.io/docs/"
  },
  "tags": [
    {
      "name": "OCR",
      "description": "Identity-document OCR extraction"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/ocr": {
      "post": {
        "operationId": "extractDocument",
        "tags": ["OCR"],
        "summary": "Extract structured fields from an identity-document image",
        "description": "Upload one image of the document's front side and pass the country-specific `documentType` (e.g. `passport`, `th_id_card`, `us_drivers_license`). Returns the document's fields as JSON. The returned fields depend on the document type — each document returns exactly what it prints.\n\nSign up at https://pictotext.io to get an API key (Dashboard → API Keys). New accounts include 100 free calls. The full `documentType` list and per-country field references live in the docs.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["image", "documentType"],
                "properties": {
                  "image": {
                    "type": "string",
                    "format": "binary",
                    "description": "Image of the document's front side. JPEG, PNG, WebP, HEIC, or HEIF; max 10 MB."
                  },
                  "documentType": {
                    "type": "string",
                    "description": "Country-specific document type identifier. `passport` covers ICAO 9303 passports worldwide; ID cards and driver's licenses use per-country codes such as `th_id_card` (Thailand), `de_id_card` (Germany), `cn_id_card` (China), `in_aadhaar_front` (India), `id_ktp` (Indonesia), `us_drivers_license` (USA). See https://pictotext.io/docs/ for the complete list.",
                    "example": "passport"
                  }
                }
              },
              "encoding": {
                "image": {
                  "contentType": "image/jpeg, image/png, image/webp, image/heic, image/heif"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted document fields. The object's keys depend on the document type (each document returns the fields it actually prints); dates are normalized to ISO 8601.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Structured document fields. Keys vary by documentType."
                },
                "example": {
                  "passportNumber": "L898902C3",
                  "name": "ANNA MARIA ERIKSSON",
                  "nationality": "UTO",
                  "birthDay": "1974-08-12",
                  "expiryDay": "2012-04-15",
                  "mrz": "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\nL898902C36UTO7408122F1204159ZE184226B<<<<<10"
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing or invalid `image`, unsupported image type, image over 10 MB, or invalid `documentType`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": 400,
                    "message": "A valid, non-auto documentType is required.",
                    "status": "Bad Request",
                    "details": [
                      {
                        "reason": "INVALID_DOCUMENT_TYPE"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": 401,
                    "message": "Invalid or inactive API key",
                    "status": "Unauthorized",
                    "details": [
                      {
                        "reason": "INVALID_API_KEY"
                      }
                    ]
                  }
                }
              }
            }
          },
          "402": {
            "description": "No remaining included quota or credits. Purchase credits or upgrade the plan to continue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": 402,
                    "message": "You have no remaining included quota or credits. Please purchase credits or upgrade your plan to continue.",
                    "status": "Payment Required",
                    "details": [
                      {
                        "reason": "INSUFFICIENT_CREDITS"
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Email verification required before using the API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": 403,
                    "message": "Email verification required before using the API.",
                    "status": "Forbidden",
                    "details": [
                      {
                        "reason": "EMAIL_NOT_VERIFIED"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The AI service failed to process the image, or an unexpected server error occurred.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": 500,
                    "message": "Failed to process image with AI service.",
                    "status": "Internal Server Error",
                    "details": [
                      {
                        "reason": "AI_SERVICE_ERROR"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from your PicToText dashboard (Dashboard → API Keys), passed as `Authorization: Bearer <API_KEY>`. Sign up at https://pictotext.io — new accounts include 100 free API calls."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "status", "details"],
            "properties": {
              "code": {
                "type": "integer",
                "description": "HTTP status code"
              },
              "message": {
                "type": "string",
                "description": "Human-readable error message"
              },
              "status": {
                "type": "string",
                "description": "HTTP status text"
              },
              "details": {
                "type": "array",
                "description": "Machine-readable error reasons",
                "items": {
                  "type": "object",
                  "properties": {
                    "reason": {
                      "type": "string"
                    },
                    "metadata": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
