> ## Documentation Index > Fetch the complete documentation index at: https://docs.origoid.com/llms.txt > Use this file to discover all available pages before exploring further. # Universal Extraction (Proof of Address) > **Credits:** 1 per call. Performs OCR on a Mexican proof-of-address document — utility bills (water, electricity, gas, internet, telephone) and bank statements — and returns the structured data printed on it. Returns: - **`provider`**: the issuing utility or institution (CFE, Telmex, Agua, etc.), so you can apply provider-specific business rules and recognize legitimate document layouts. - **`personalInfo`**: holder name as printed on the document. - **`address`**: full address as printed (street, exterior / interior number, neighborhood, municipality, state, postal code). - **`billing`**: issuance date, account number, period covered. - **`validations`**: flags about document age, document type detection confidence, and structural consistency checks. Use this endpoint to automate address verification in KYC flows. The extracted address can be cross-checked against the address your customer submitted at signup. ## OpenAPI ````yaml /openapi.json post /mex/documents/v1/proof-of-address-extractions openapi: 3.0.3 info: title: OrigoID API description: >- Identity and Background Verification API for Mexico. ### Authentication The API Gateway supports the following methods. You must send **one** of them in the headers: 1. **API Key**: `x-api-key: YOUR_KEY` 2. **Bearer Token**: `Authorization: Bearer YOUR_TOKEN` 3. **Basic Auth**: `Authorization: Basic BASE64` ### Standard Format All responses follow this structure (HTTP 200). Authentication errors return 401. ```json { "status": "OK | ERROR", "type": "TYPE_CODE", "message": "Description", "data": { ... }, "transactionId": "uuid", "processedAt": "2026-03-19T10:00:00-06:00", "billable": true } ``` ### Rate Limiting The API enforces per-endpoint rate limits, calculated on a sliding 1-minute window. Limits are defined per user, with a global default that can be overridden individually or by payment plan. When a limit is exceeded, the API returns HTTP `429 Too Many Requests` with the following headers: - **`Retry-After`**: seconds to wait before retrying. - **`X-RateLimit-Limit`**: total requests allowed in the current window. - **`X-RateLimit-Remaining`**: requests remaining in the current window. - **`X-RateLimit-Reset`**: Unix timestamp (seconds) when the window resets. Clients should implement backoff using `Retry-After`. The response body follows the standard envelope with `type: RATE_LIMIT_EXCEEDED`. ### Language Conventions The API follows a strict bilingual contract: - **All API-facing copy is in English**: response messages, error codes, field names, schema descriptions, summaries, and tag descriptions. - **Passthrough fields preserve the original Spanish text** sourced verbatim from Mexican regulators (SAT, RENAPO, IMSS, INE). These include: - `officialMessage` — official regulator response text. - Fields inside `taxRegimes` and `taxObligations` arrays from CSF (`description`, `dueDate`, etc.) — preserved exactly as published by SAT. - Address components extracted from documents (street names, neighborhood names) — preserved as printed. - Compliance match fields like `position`, `institution` from PEPs — preserved as recorded by the source. Do not translate passthrough fields — their value lies in legal traceability to the original source. ### Image Processing Policy Endpoints that accept images follow a **best-effort processing** philosophy: - **Hard Limits** (max file size, supported formats) are strictly enforced. A request that exceeds them is rejected with `INVALID_REQUEST` before any processing occurs. - **Recommendations** (resolution, file size for latency, framing, lighting) are guidance — not enforced. Suboptimal images that meet the Hard Limits are still processed. - If extraction fails on a low-quality image, the endpoint returns the appropriate type code (`IMAGE_UNREADABLE`, `NO_FACE_DETECTED`, `DOCUMENT_NOT_IDENTIFIED`, etc.) with `billable: true` — processing did run and consumed resources. This policy exists because integrators often cannot control their capture SDK output (third-party SDKs, legacy systems, browser-based capture). Rejecting suboptimal images would block legitimate use cases. Processing best-effort and reporting honest results gives the integrator the information needed to decide whether to retry or accept the result. ### Date and Time Conventions All temporal fields across the API follow standardized formats: - **`processedAt`**: ISO 8601 datetime with Mexico City offset (`-06:00`). Example: `2026-03-19T10:00:00-06:00`. - **Date-only fields** (`dateOfBirth`, `dueDate`, `issueDate`, `publicationDate`, `publicationDateSat`, `publicationDateDof`, `constitutionDate`, `startDate`, `registrationDate`, `lastStatusChangeDate`): ISO 8601 date (`YYYY-MM-DD`). Example: `2024-01-10`. - **Year-month fields** (`reportPeriod`, `positionEndDate`): ISO 8601 year-month (`YYYY-MM`). Example: `2026-02`. (`positionEndDate` is normalised from the source — the PEP provider publishes the month and year a former office-holder left office, e.g. `Septiembre de 2024` becomes `2024-09`.) - **Year-only fields** (`year`, `emissionYear`, `registrationYear`, `validUntilYear`): returned as 4-digit string (e.g. `"2022"`). Strings preserve the raw value sourced from the document; clients may safely parse to integer. - **Money fields** (`baseSalary`, `amountDue`, `taxAmount`): object `{ amount: "", currency: "" }`. Amounts are decimal strings (not floats) to avoid precision errors. Example: `{ "amount": "452.50", "currency": "MXN" }`. --- # Catalogs #### 1. CURP Status (`statusCurp`) Status code returned by RENAPO inside `personalInfo.statusCurp` and similar fields. | `statusCurp` | State | Description | | :--- | :--- | :--- | | `AN` | Active | Normal registration (Alta Normal). Valid and current. | | `AH` | Active | Homonymy alert (Alta con Homonimia). First 16 chars match another CURP. | | `RCC` | Active | Change affecting CURP (Registro con Cambio). Data correction modified the key. | | `RCN` | Active | Change not affecting CURP. Minor data correction. | | `BAP` | Inactive | Apocryphal document (Baja por documento apócrifo). | | `BSU` | Inactive | Unused (Baja sin uso). Requires reactivation at a RENAPO module. | | `BD` | Inactive | Deceased (Baja por defunción). | | `BDM` | Inactive | Administrative cancellation (Baja administrativa). | | `BDP` | Inactive | Adoption-related cancellation (Baja por adopción). | | `BJD` | Inactive | Judicial cancellation (Baja judicial). | #### 2. Probatory Document (`docProbatorio`) Code identifying which civil document supports the CURP registration. | `docProbatorio` | Document | | :--- | :--- | | `1` | Birth Certificate (Acta de Nacimiento) | | `3` | Migration Document (Documento Migratorio) | | `4` | Naturalization Certificate (Carta de Naturalización) | | `7` | Mexican Nationality Certificate (Certificado de Nacionalidad Mexicana) | | `8` | SEGOB Processing (Trámite ante SEGOB) | #### 3. Mexican State Codes (`entidad` / `claveEntidad`) Two-letter codes used in CURP, RFC composition, INE registration, and addresses. State names preserved in Spanish (proper nouns). | `entidad` | State | `entidad` | State | | :--- | :--- | :--- | :--- | | `AS` | Aguascalientes | `QR` | Quintana Roo | | `BC` | Baja California | `SP` | San Luis Potosí | | `BS` | Baja California Sur | `SL` | Sinaloa | | `CC` | Campeche | `SR` | Sonora | | `CL` | Coahuila | `TC` | Tabasco | | `CM` | Colima | `TS` | Tamaulipas | | `CS` | Chiapas | `TL` | Tlaxcala | | `CH` | Chihuahua | `VZ` | Veracruz | | `DF` | Ciudad de México | `YN` | Yucatán | | `DG` | Durango | `ZS` | Zacatecas | | `GT` | Guanajuato | `NE` | Born Abroad (Nacido en el Extranjero) | | `GR` | Guerrero | `MC` | Estado de México | | `HG` | Hidalgo | `MN` | Michoacán | | `JC` | Jalisco | `MS` | Morelos | | `NT` | Nayarit | `NL` | Nuevo León | | `OC` | Oaxaca | `PL` | Puebla | | `QT` | Querétaro | | | #### 4. IMSS Coverage Modalities (`modalidad`) IMSS modality codes describe the worker's affiliation type. Official descriptions preserved in Spanish for legal traceability with the institute. | `modalidad` | Description | | :--- | :--- | | `10` | Urban permanent and temporary workers (Trabajadores permanentes y eventuales de la ciudad) | | `13` | Rural temporary workers (Trabajadores eventuales del campo) | | `14` | Rural permanent workers (Trabajadores permanentes del campo) | | `17` | Re-entry rural temporary workers (Reingreso de trabajadores eventuales del campo) | | `18` | Re-entry rural permanent workers (Reingreso de trabajadores permanentes del campo) | | `30` | Re-entry urban permanent and temporary workers (Reingreso de trabajadores permanentes y eventuales de la ciudad) | | `31` | Voluntary continuation in the mandatory regime (Continuación voluntaria al régimen obligatorio) | | `32` | Independent workers (Trabajadores independientes) | | `33` | Domestic workers (Trabajadores domésticos) | | `34` | Federal or state government workers (Trabajadores del gobierno federal o estatal) | | `35` | IMSS-affiliated students (Estudiantes afiliados al IMSS) | | `36` | Scholarship holders or social programs (Becarios o programas sociales) | | `40` | Voluntary continuation in the mandatory regime (alternate) | | `42` | Individual employer with domestic workers (Patrón persona física con trabajadores domésticos) | | `43` | International organization workers (Trabajadores de organismos internacionales) | | `44` | Seasonal or fixed-term workers (Trabajadores por temporada o tiempo determinado) | | `45` | Re-entered retirees in mandatory regime (Pensionados reincorporados al régimen obligatorio) | | `46` | Construction temporary workers (Trabajadores eventuales de la construcción) | | `47` | Trust workers with special regime (Trabajadores de confianza con régimen especial) | | `48` | Affiliated municipal public servants (Servidores públicos municipales afiliados) | | `50` | Voluntary continuation with extended coverage (Continuación voluntaria con cobertura extendida) | | `51` | Voluntary affiliation for students or apprentices (Afiliación voluntaria para estudiantes o aprendices) | | `60` | Special social incorporation regime — RESICO (Régimen especial de incorporación social) | | `70` | IMSS-Bienestar or community programs modality | | `72` | Inter-agency public agreement with IMSS (Convenio entre dependencias públicas y el IMSS) | #### 5. SAT Article 69 Sub-lists (`listType`) | `listType` | Sub-list (SAT) | Risk Level | | :--- | :--- | :--- | | SAT_69_FIRMES | Firmes | MEDIUM | | SAT_69_CANCELADOS | Cancelados (Insolvencia, general) | MEDIUM | | SAT_69_CANCELADOS_07_15 | Cancelados 2007–2015 (Art. 146-A) | MEDIUM | | SAT_69_EXIGIBLES | Exigibles | MEDIUM | | SAT_69_NO_LOCALIZADOS | No Localizados | HIGH | | SAT_69_CSD_SIN_EFECTOS | Certificados de Sello Digital (CSD) sin Efectos | HIGH | | SAT_69_SENTENCIAS | Sentencias | CRITICAL | | SAT_69_REDUCCION_74_CFF | Reducción Art. 74 CFF | LOW | | SAT_69_CONDONADOS_07_15 | Condonados 2007–2015 (Decreto) | LOW | | SAT_69_CONDONADOS_146B_CFF | Condonados Art. 146-B CFF | LOW | | SAT_69_CONDONADOS_DECRETO | Condonados por Decreto | LOW | | SAT_69_CONDONADOS_21_CFF | Condonados Art. 21 CFF | LOW | | SAT_69_RETORNO_INVERSIONES | Retorno de Inversiones | LOW | | SAT_69_ENTES_PUBLICOS_OMISOS | Entes Públicos y de Gobierno Omisos | LOW | #### 6. SAT Article 69-B Status (`complianceDetails.status`) The SAT 69-B endpoint always returns `listType: SAT_69B`. The granular state lives in `complianceDetails.status`: | `status` | Description | Risk Level | | :--- | :--- | :--- | | PRESUNTO | Currently under investigation for simulated operations (EFOS) | HIGH | | DEFINITIVO | Confirmed shell company / EFOS | CRITICAL | | DESVIRTUADO | Investigated but successfully proved innocence | LOW | | SENTENCIA_FAVORABLE | Won in court / cleared by judicial ruling | LOW | #### 7. PEPs Categories (`listType`) These are OrigoID's stable taxonomy codes. They remain consistent over time so client integrations don't need to change when data sources evolve. | `listType` | Description | Risk Level | | :--- | :--- | :--- | | PEP_ACTIVE | Politically Exposed Person — currently in office | HIGH | | PEP_INACTIVE | Politically Exposed Person — record marked inactive by the source | MEDIUM | | EX_PEP | Former PEP — held office in the past | MEDIUM | | PEP_AFFINITY | Family member or close associate of an active PEP | MEDIUM | | EX_PEP_AFFINITY | Family member or close associate of a former PEP | LOW | #### 8. OFAC Lists (`listType`) We query the official OFAC sanctions lists in real time and consolidate them under the `listType` codes below. Each entry also exposes `complianceDetails.programs[]` (sanction program codes such as CUBA, IRAN, RUSSIA, etc. — these evolve continuously and are not statically catalogued) and `complianceDetails.entityType` (`INDIVIDUAL` | `ENTITY` | `VESSEL` | `AIRCRAFT`). | `listType` | Official OFAC list | Risk Level | | :--- | :--- | :--- | | OFAC_SDN | Specially Designated Nationals & Blocked Persons | CRITICAL | | OFAC_NON_SDN | Consolidated Non-SDN List | HIGH | | OFAC_FSE | Foreign Sanctions Evaders | CRITICAL | | OFAC_NS_ISA | Non-SDN Iran Sanctions Act List | HIGH | | OFAC_SSI | Sectoral Sanctions Identifications List | MEDIUM | | OFAC_CAPTA | Foreign Financial Institutions subject to Correspondent / Payable-Through Account Sanctions | HIGH | | OFAC_NS_PLC | Non-SDN Palestinian Legislative Council | LOW | #### 9. CFDI Effect (`effect`) Fiscal purpose of the invoice as classified by SAT. Each CFDI has exactly one effect. | `effect` | SAT code | Description | | :--- | :--- | :--- | | INCOME | I (Ingreso) | Sales / revenue invoice. Issuer received payment for goods or services. | | EXPENSE | E (Egreso) | Refund, credit note, or discount. Reverses or reduces a previous income invoice. | | TRANSPORT | T (Traslado) | Goods transport waybill (Carta Porte). Does not reflect a sale, only movement of goods. | | PAYROLL | N (Nómina) | Payroll receipt issued by an employer to an employee. | | PAYMENT | P (Pago) | Payment receipt complement (REP) for invoices paid in installments (PPD). | #### 10. CFDI Status (`status`) Current fiscal status of the CFDI according to SAT's verification service. | `status` | Description | | :--- | :--- | | VALID | Vigente. The CFDI is current and fiscally valid. | | CANCELED | Cancelada. The CFDI has been canceled and is no longer fiscally valid. | #### 11. CFDI Cancellation Status (`cancellationStatus`) Reflects SAT's 2022 cancellation rules ("cancelación con aceptación"), which require receiver consent in some scenarios. This field shows both pre-cancellation eligibility and post-cancellation outcome. | `cancellationStatus` | Description | | :--- | :--- | | NOT_CANCELABLE | Cannot be canceled (e.g. payment complements, payroll receipts, or invoices linked to other active CFDIs). | | CANCELABLE_WITHOUT_ACCEPTANCE | The issuer may cancel unilaterally (small amounts, payroll corrections, etc.). | | CANCELABLE_WITH_ACCEPTANCE | The issuer can request cancellation, but the receiver must accept it within 72 hours. | | CANCELED_WITHOUT_ACCEPTANCE | Already canceled; acceptance was not required. | | CANCELED_WITH_ACCEPTANCE | Already canceled; the receiver approved the cancellation. | --- **Soporte:** contacto@origoid.com version: 1.0.0 contact: name: Soporte OrigoId email: contacto@origoid.com servers: - url: https://api.origoid.com security: - ApiKeyAuth: [] - BearerAuth: [] - BasicAuth: [] tags: - name: Authentication description: Generation of temporary bearer tokens (JWT). - name: RENAPO description: Official identity and CURP validation. - name: INE description: Validation of Nominal Lists and Voter Credentials. - name: Social Security description: Employment and social security data. - name: Biometrics description: Facial biometric comparison against identity documents. - name: Compliance description: 'Sanctions and risk lists: SAT 69, SAT 69-B, OFAC, and PEPs.' - name: Email description: Email deliverability and fraud risk validation. - name: Proof of Address description: >- Data extraction from utility and proof-of-address documents (CFE, Telmex, Telcel, etc.). - name: Fiscal description: RFC validation and CSF (Constancia de Situación Fiscal) extraction. - name: Banking description: SPEI / CEP payment validation against Banco de México. paths: /mex/documents/v1/proof-of-address-extractions: post: tags: - Proof of Address summary: Universal Extraction (Proof of Address) description: >- **Credits:** 1 per call. Performs OCR on a Mexican proof-of-address document — utility bills (water, electricity, gas, internet, telephone) and bank statements — and returns the structured data printed on it. Returns: - **`provider`**: the issuing utility or institution (CFE, Telmex, Agua, etc.), so you can apply provider-specific business rules and recognize legitimate document layouts. - **`personalInfo`**: holder name as printed on the document. - **`address`**: full address as printed (street, exterior / interior number, neighborhood, municipality, state, postal code). - **`billing`**: issuance date, account number, period covered. - **`validations`**: flags about document age, document type detection confidence, and structural consistency checks. Use this endpoint to automate address verification in KYC flows. The extracted address can be cross-checked against the address your customer submitted at signup. operationId: extractProofOfAddress requestBody: required: true content: application/json: schema: type: object required: - file properties: file: type: string description: Proof of Address file in Base64 (PNG, JPG, or PDF). responses: '200': description: Extraction results (Strict Envelope Pattern). content: application/json: examples: Success CFE: summary: Success CFE value: status: OK type: SUCCESS message: Proof of address processed successfully data: documentType: PROOF_OF_ADDRESS provider: CFE personalInfo: fullName: CARLOS MENDOZA RUIZ phoneNumber: null address: street: CALLE DE LOS PINOS 45 INT 3 neighborhood: JARDINES DEL VALLE city: ZAPOPAN state: JAL zipCode: '45138' reference: ENTRE ROBLES Y CEDROS fullAddressRaw: >- CALLE DE LOS PINOS 45 INT 3 JARDINES DEL VALLE C.P. 45138 ZAPOPAN , JAL . billing: accountNumber: '847291038472' amountDue: amount: '452.50' currency: MXN dueDate: '2023-11-20' paymentCode: '01847291038472311200000004525' validations: isRecent: false monthsOld: 28 transactionId: f47ac10b-58cc-4372-a567-0e02b2c3d479 processedAt: '2026-03-15T12:30:00-06:00' billable: true Success Telmex: summary: Success Telmex value: status: OK type: SUCCESS message: Proof of address processed successfully data: documentType: PROOF_OF_ADDRESS provider: TELMEX personalInfo: fullName: MARTINEZ LOPEZ ANA MARIA phoneNumber: '2221234567' address: street: AVENIDA REFORMA 1200 neighborhood: ZONA CENTRO city: PUEBLA state: PUE zipCode: '72000' reference: FRENTE AL PARQUE fullAddressRaw: AVENIDA REFORMA 1200 ZONA CENTRO 72000 PUEBLA , PUE billing: accountNumber: '120119090117996' amountDue: amount: '899.00' currency: MXN dueDate: '2024-01-10' paymentCode: '88829374610293847561' validations: isRecent: true monthsOld: 2 transactionId: 7e32a10c-58cc-4372-a567-0e02b2c3d479 processedAt: '2026-03-15T12:30:00-06:00' billable: true Success Telcel: summary: Success Telcel value: status: OK type: SUCCESS message: Proof of address processed successfully data: documentType: PROOF_OF_ADDRESS provider: TELCEL personalInfo: fullName: GOMEZ SANCHEZ LUIS phoneNumber: '8112442056' address: street: AV INSURGENTES SUR 123 neighborhood: ROMA NORTE city: CUAUHTEMOC state: CDMX zipCode: '06700' reference: null fullAddressRaw: >- AV INSURGENTES SUR 123 ROMA NORTE 06700 CUAUHTEMOC, CDMX billing: accountNumber: '0048192837' amountDue: amount: '599.00' currency: MXN dueDate: '2023-08-12' paymentCode: '820404159349061300059900' validations: isRecent: false monthsOld: 31 transactionId: 038c272c-92de-4944-8e2e-e11b0ba75441 processedAt: '2026-03-15T12:30:00-06:00' billable: true Success Megacable: summary: Success Megacable value: status: OK type: SUCCESS message: Proof of address processed successfully data: documentType: PROOF_OF_ADDRESS provider: MEGACABLE personalInfo: fullName: FERNANDEZ LOPEZ MARIA phoneNumber: '4773326489' address: street: BLVD BERNARDO QUINTANA 45 neighborhood: CENTRO SUR city: QUERETARO state: QRO zipCode: '76090' reference: ENTRE PRIVADA Y ESQUINA fullAddressRaw: >- BLVD BERNARDO QUINTANA 45 CENTRO SUR 76090 QUERETARO, QRO billing: accountNumber: '0471829304' amountDue: amount: '850.00' currency: MXN dueDate: '2023-10-15' paymentCode: '17047182930423101500850009' validations: isRecent: false monthsOld: 29 transactionId: 64098a46-075e-49cf-b7d2-c3b6b77e00f1 processedAt: '2026-03-15T12:30:00-06:00' billable: true Success Izzi: summary: Success Izzi value: status: OK type: SUCCESS message: Proof of address processed successfully data: documentType: PROOF_OF_ADDRESS provider: IZZI personalInfo: fullName: HERNANDEZ DIAZ SOFIA phoneNumber: '9292928293' address: street: AV LA PAZ 204 neighborhood: AMERICANA city: GUADALAJARA state: JAL zipCode: '44160' reference: null fullAddressRaw: AV LA PAZ 204 AMERICANA 44160 GUADALAJARA, JAL billing: accountNumber: '90028374' amountDue: amount: '650.00' currency: MXN dueDate: '2023-07-20' paymentCode: '0900283741' validations: isRecent: false monthsOld: 32 transactionId: 617eb71f-1872-4864-b09d-24884bc01c79 processedAt: '2026-03-15T12:30:00-06:00' billable: true Success Totalplay: summary: Success Totalplay value: status: OK type: SUCCESS message: Proof of address processed successfully data: documentType: PROOF_OF_ADDRESS provider: TOTALPLAY personalInfo: fullName: SORIANO MARTINEZ JUAN phoneNumber: '5512345678' address: street: AV PASEO DE LA REFORMA 250 neighborhood: JUAREZ city: CUAUHTEMOC state: CDMX zipCode: '06600' reference: PISO 10 fullAddressRaw: >- AV PASEO DE LA REFORMA 250 JUAREZ 06600 CUAUHTEMOC, CDMX billing: accountNumber: '0102030405' amountDue: amount: '789.00' currency: MXN dueDate: '2024-02-15' paymentCode: '12345678901234567890' validations: isRecent: false monthsOld: 25 transactionId: 8bfaed16-591d-45da-bfdc-0300050928db processedAt: '2026-03-15T12:30:00-06:00' billable: true Error Unreadable: summary: Unreadable Image value: status: OK type: IMAGE_UNREADABLE message: The document is too blurry or obscured to extract data data: null transactionId: a1b2c3d4-e5f6-7a8b-9c0d-123456789012 processedAt: '2026-03-15T12:30:00-06:00' billable: true Error Unsupported: summary: Unsupported Provider value: status: OK type: DOCUMENT_NOT_SUPPORTED message: >- The provided document is not a recognized Mexican proof of address data: null transactionId: e1f2a3b4-5c6d-7e8f-9a0b-123456789013 processedAt: '2026-03-15T12:30:00-06:00' billable: true Validation Error: summary: Validation Error value: status: ERROR type: INVALID_REQUEST message: Validation failed data: null errors: - field: file code: MISSING_REQUIRED_FIELD message: must have required property 'file' - field: file code: INVALID_FORMAT message: file must be a valid PNG, JPG, or PDF - field: body code: PAYLOAD_TOO_LARGE message: body exceeds the maximum allowed size transactionId: 9d8c7b6a-5e4d-3c2b-1a0f-9e8d7c6b5a4b processedAt: '2026-03-15T12:30:00-06:00' billable: false Internal Error: summary: Internal Error value: status: ERROR type: INTERNAL_ERROR message: Unexpected internal error data: null transactionId: c3d4e5f6-a7b8-9c0d-1e2f-123456789015 processedAt: '2026-03-15T12:30:00-06:00' billable: false schema: $ref: '#/components/schemas/Envelope' '401': description: Unauthorized content: application/json: examples: Unauthorized: summary: Unauthorized value: status: ERROR type: UNAUTHORIZED message: Invalid credentials data: null transactionId: 71d64fd8-8a54-4792-a844-7e2466eb01f7 processedAt: '2026-05-21T10:00:00-06:00' billable: false schema: $ref: '#/components/schemas/Envelope' '429': description: Too Many Requests — endpoint rate limit exceeded. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. X-RateLimit-Limit: schema: type: integer description: >- Total requests allowed in the current window (per minute, per endpoint, per user/plan). X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: integer description: Unix timestamp (seconds) when the rate limit window resets. content: application/json: examples: Rate Limit: summary: Rate Limit Exceeded value: status: ERROR type: RATE_LIMIT_EXCEEDED message: >- API rate limit exceeded for this endpoint. Retry after the duration specified in the Retry-After header. data: null transactionId: 46ac6ecd-ae59-4247-8a29-591f81b8f9c7 processedAt: '2026-04-26T10:00:00-06:00' billable: false schema: $ref: '#/components/schemas/Envelope' x-codeSamples: - lang: cURL source: >- curl -X POST https://api.origoid.com/mex/documents/v1/proof-of-address-extractions \ -H "x-api-key: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{"file": ""}' - lang: JavaScript source: >- const response = await fetch("https://api.origoid.com/mex/documents/v1/proof-of-address-extractions", { method: "POST", headers: { "x-api-key": process.env.ORIGOID_API_KEY, "content-type": "application/json", }, body: JSON.stringify({ "file": "" }), }); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } const result = await response.json(); console.log(result); - lang: Python source: |- import os import requests response = requests.post( "https://api.origoid.com/mex/documents/v1/proof-of-address-extractions", headers={ "x-api-key": os.environ["ORIGOID_API_KEY"], "content-type": "application/json", }, json={ "file": "" }, timeout=30, ) response.raise_for_status() result = response.json() print(result) - lang: Java source: |- import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class Example { public static void main(String[] args) throws Exception { String payload = "{\"file\": \"\"}"; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.origoid.com/mex/documents/v1/proof-of-address-extractions")) .header("x-api-key", System.getenv("ORIGOID_API_KEY")) .header("content-type", "application/json") .timeout(Duration.ofSeconds(30)) .POST(HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println(response.statusCode()); System.out.println(response.body()); } } - lang: PHP source: >- "}'; $ch = curl_init('https://api.origoid.com/mex/documents/v1/proof-of-address-extractions'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ 'x-api-key: ' . getenv('ORIGOID_API_KEY'), 'content-type: application/json', ], ]); $response = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status >= 400) { throw new Exception("HTTP $status"); } $result = json_decode($response, true); print_r($result); - lang: Go source: "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"log\"\n\t\"net/http\"\n\t\"os\"\n\t\"time\"\n)\n\nfunc main() {\n\tpayload := []byte(`{\"file\": \"\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/documents/v1/proof-of-address-extractions\", bytes.NewBuffer(payload))\n\tif err != nil { log.Fatal(err) }\n\treq.Header.Set(\"x-api-key\", os.Getenv(\"ORIGOID_API_KEY\"))\n\treq.Header.Set(\"content-type\", \"application/json\")\n\n\tclient := &http.Client{Timeout: 30 * time.Second}\n\tresp, err := client.Do(req)\n\tif err != nil { log.Fatal(err) }\n\tdefer resp.Body.Close()\n\n\tvar result map[string]any\n\tif err := json.NewDecoder(resp.Body).Decode(&result); err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Println(result)\n}" - lang: C# source: |- using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; class Program { static async Task Main() { using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) }; client.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("ORIGOID_API_KEY")); var payload = "{\"file\": \"\"}"; var content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.PostAsync("https://api.origoid.com/mex/documents/v1/proof-of-address-extractions", content); response.EnsureSuccessStatusCode(); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine(body); } } components: schemas: Envelope: type: object required: - status - type - message - transactionId - processedAt - billable properties: status: type: string enum: - OK - ERROR description: >- High-level outcome. `OK` means the request was successfully processed (regardless of business result). `ERROR` means the request was rejected or could not be processed. type: type: string description: >- Stable result type code. Includes generic codes (`SUCCESS`, `INVALID_REQUEST`, `UNAUTHORIZED`, `SERVICE_UNAVAILABLE`, `INTERNAL_ERROR`, `RATE_LIMIT_EXCEEDED`) plus endpoint-specific result codes — see this endpoint's response examples. message: type: string description: >- Human-readable summary of the result. Always in English (per Language Conventions in the API overview). data: type: object nullable: true description: >- Response payload. `null` on error responses. Shape depends on the endpoint — see each operation's response schema. errors: type: array description: >- Per-field error details. Present only on `INVALID_REQUEST` responses. items: $ref: '#/components/schemas/ErrorDetail' transactionId: type: string format: uuid description: >- Unique identifier of this request, generated by the API Gateway. Propagated end-to-end for traceability. processedAt: type: string format: date-time description: >- ISO 8601 datetime with Mexico City offset (`-06:00`). Always set by the API Gateway when the response leaves the system. billable: type: boolean description: >- Whether this request will be charged against the client's plan. Typically `true` for successful business results and `false` for validation errors or system errors that prevented processing. ErrorDetail: type: object required: - field - code - message properties: field: type: string description: >- JSON path or field name where the validation failed. For body-level errors (malformed JSON, payload exceeds size limit, oneOf with all alternatives present) use `body`. For field-specific errors use the dotted path (e.g. `rfc`, `personalInfo.curp`, `front`). code: type: string description: >- Machine-readable error code. Standard catalog (non-exhaustive): `MISSING_REQUIRED_FIELD`, `INVALID_TYPE`, `INVALID_FORMAT`, `INVALID_ENUM_VALUE`, `INVALID_LENGTH`, `OUT_OF_RANGE`, `INVALID_ARRAY`, `UNKNOWN_FIELD`, `SCHEMA_MISMATCH`, `MISSING_DEPENDENT_FIELD`, `MALFORMED_JSON`, `PAYLOAD_TOO_LARGE`, `INVALID_SCOPE`, `INVALID_VALUE`. Some operations also emit endpoint-specific codes documented in each operation's spec (e.g. `INVALID_RFC_FORMAT`, `NAME_TOO_SHORT`, `QR_NOT_FOUND`). message: type: string description: Human-readable description of the field-level error. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key BearerAuth: type: http scheme: bearer bearerFormat: JWT BasicAuth: type: http scheme: basic ````