{ "openapi": "3.0.3", "info": { "title": "OrigoID API", "description": "Identity and Background Verification API for Mexico.\n\n### Authentication\nThe API Gateway supports the following methods. You must send **one** of them in the headers:\n\n1. **API Key**: `x-api-key: YOUR_KEY`\n2. **Bearer Token**: `Authorization: Bearer YOUR_TOKEN`\n3. **Basic Auth**: `Authorization: Basic BASE64`\n\n### Standard Format\nAll responses follow this structure (HTTP 200). Authentication errors return 401.\n```json\n{\n \"status\": \"OK | ERROR\",\n \"type\": \"TYPE_CODE\",\n \"message\": \"Description\",\n \"data\": { ... },\n \"transactionId\": \"uuid\",\n \"processedAt\": \"2026-03-19T10:00:00-06:00\",\n \"billable\": true\n}\n```\n\n### Rate Limiting\nThe 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.\n\nWhen a limit is exceeded, the API returns HTTP `429 Too Many Requests` with the following headers:\n\n- **`Retry-After`**: seconds to wait before retrying.\n- **`X-RateLimit-Limit`**: total requests allowed in the current window.\n- **`X-RateLimit-Remaining`**: requests remaining in the current window.\n- **`X-RateLimit-Reset`**: Unix timestamp (seconds) when the window resets.\n\nClients should implement backoff using `Retry-After`. The response body follows the standard envelope with `type: RATE_LIMIT_EXCEEDED`.\n\n### Language Conventions\nThe API follows a strict bilingual contract:\n\n- **All API-facing copy is in English**: response messages, error codes, field names, schema descriptions, summaries, and tag descriptions.\n- **Passthrough fields preserve the original Spanish text** sourced verbatim from Mexican regulators (SAT, RENAPO, IMSS, INE). These include:\n - `officialMessage` — official regulator response text.\n - Fields inside `taxRegimes` and `taxObligations` arrays from CSF (`description`, `dueDate`, etc.) — preserved exactly as published by SAT.\n - Address components extracted from documents (street names, neighborhood names) — preserved as printed.\n - Compliance match fields like `position`, `institution` from PEPs — preserved as recorded by the source.\n\nDo not translate passthrough fields — their value lies in legal traceability to the original source.\n\n### Image Processing Policy\nEndpoints that accept images follow a **best-effort processing** philosophy:\n\n- **Hard Limits** (max file size, supported formats) are strictly enforced. A request that exceeds them is rejected with `INVALID_REQUEST` before any processing occurs.\n- **Recommendations** (resolution, file size for latency, framing, lighting) are guidance — not enforced. Suboptimal images that meet the Hard Limits are still processed.\n- 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.\n\nThis 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.\n\n### Date and Time Conventions\nAll temporal fields across the API follow standardized formats:\n\n- **`processedAt`**: ISO 8601 datetime with Mexico City offset (`-06:00`). Example: `2026-03-19T10:00:00-06:00`.\n- **Date-only fields** (`dateOfBirth`, `dueDate`, `issueDate`, `publicationDate`, `publicationDateSat`, `publicationDateDof`, `constitutionDate`, `startDate`, `endDate`, `registrationDate`, `lastStatusChangeDate`): ISO 8601 date (`YYYY-MM-DD`). Example: `2024-01-10`.\n- **Year-month fields** (`reportPeriod`, `currentMonth`, `nextReportMonth`, `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`.)\n- **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.\n- **Money fields** (`baseSalary`, `amountDue`, `taxAmount`): object `{ amount: \"\", currency: \"\" }`. Amounts are decimal strings (not floats) to avoid precision errors. Example: `{ \"amount\": \"452.50\", \"currency\": \"MXN\" }`.\n\n### Asynchronous Endpoints (Webhooks)\nSome IMSS queries take longer than a client should wait on an open HTTP request, so they are also offered as **asynchronous** endpoints: **Get NSS (Async)**, **Employment Status (Async)** and **Contribution Weeks**. They work in two steps:\n\n1. **Create the request.** `POST` the query together with a `webhook` object. The API answers right away with `type: ACCEPTED` and a `transactionId`, with `billable: false` — accepting a request is free. An invalid request is rejected right away with `INVALID_REQUEST` and is never charged.\n2. **Receive the result on your webhook.** When the query resolves, we send an HTTP `POST` to `webhook.url` with a JSON body: the standard envelope (`status`, `type`, `message`, `data`, `transactionId`, `processedAt`, `billable`) carrying the **same `transactionId`** returned in step 1. Credits are charged once, when the result resolves, under the same rule as every other endpoint: `billable: true` when the query was performed (even with a negative outcome), `false` for technical failures.\n\n**`webhook` object**\n- `url` (required): public `http` or `https` URL that receives the result.\n- `headers` (optional): header names and values we add to the webhook request — for example, your own token, so your endpoint can authenticate the call.\n\n**Your webhook endpoint should**\n- Answer with any `2xx` status as soon as it receives the body, and process it afterwards.\n- Be idempotent: the same result may be delivered more than once, so use `transactionId` to de-duplicate.\n\n**Delivery attempts.** We try to deliver each result up to **3 times**: right away, then 1 minute and 5 minutes after the previous failed attempt. An attempt fails when your endpoint does not answer with a `2xx` status within 10 seconds (redirects are not followed). After the third failed attempt the result is not sent again. Keeping your endpoint available is your responsibility: credits are charged when the result resolves, whether or not your endpoint receives it. For Contribution Weeks, the result can still be fetched for 24 hours with **Contribution Weeks Result**.\n\nResult types, with one example each, for every asynchronous endpoint: https://docs.origoid.com/en/webhooks\n\n---\n\n# Catalogs\n\n#### 1. CURP Status (`statusCurp`)\n\nStatus code returned by RENAPO inside `personalInfo.statusCurp` and similar fields.\n\n| `statusCurp` | State | Description |\n| :--- | :--- | :--- |\n| `AN` | Active | Normal registration (Alta Normal). Valid and current. |\n| `AH` | Active | Homonymy alert (Alta con Homonimia). First 16 chars match another CURP. |\n| `RCC` | Active | Change affecting CURP (Registro con Cambio). Data correction modified the key. |\n| `RCN` | Active | Change not affecting CURP. Minor data correction. |\n| `BAP` | Inactive | Apocryphal document (Baja por documento apócrifo). |\n| `BSU` | Inactive | Unused (Baja sin uso). Requires reactivation at a RENAPO module. |\n| `BD` | Inactive | Deceased (Baja por defunción). |\n| `BDM` | Inactive | Administrative cancellation (Baja administrativa). |\n| `BDP` | Inactive | Adoption-related cancellation (Baja por adopción). |\n| `BJD` | Inactive | Judicial cancellation (Baja judicial). |\n\n#### 2. Probatory Document (`docProbatorio`)\n\nCode identifying which civil document supports the CURP registration.\n\n| `docProbatorio` | Document |\n| :--- | :--- |\n| `1` | Birth Certificate (Acta de Nacimiento) |\n| `3` | Migration Document (Documento Migratorio) |\n| `4` | Naturalization Certificate (Carta de Naturalización) |\n| `7` | Mexican Nationality Certificate (Certificado de Nacionalidad Mexicana) |\n| `8` | SEGOB Processing (Trámite ante SEGOB) |\n\n#### 3. Mexican State Codes (`entidad` / `claveEntidad`)\n\nTwo-letter codes used in CURP, RFC composition, INE registration, and addresses. State names preserved in Spanish (proper nouns).\n\n| `entidad` | State | `entidad` | State |\n| :--- | :--- | :--- | :--- |\n| `AS` | Aguascalientes | `QR` | Quintana Roo |\n| `BC` | Baja California | `SP` | San Luis Potosí |\n| `BS` | Baja California Sur | `SL` | Sinaloa |\n| `CC` | Campeche | `SR` | Sonora |\n| `CL` | Coahuila | `TC` | Tabasco |\n| `CM` | Colima | `TS` | Tamaulipas |\n| `CS` | Chiapas | `TL` | Tlaxcala |\n| `CH` | Chihuahua | `VZ` | Veracruz |\n| `DF` | Ciudad de México | `YN` | Yucatán |\n| `DG` | Durango | `ZS` | Zacatecas |\n| `GT` | Guanajuato | `NE` | Born Abroad (Nacido en el Extranjero) |\n| `GR` | Guerrero | `MC` | Estado de México |\n| `HG` | Hidalgo | `MN` | Michoacán |\n| `JC` | Jalisco | `MS` | Morelos |\n| `NT` | Nayarit | `NL` | Nuevo León |\n| `OC` | Oaxaca | `PL` | Puebla |\n| `QT` | Querétaro | | |\n\n#### 4. IMSS Coverage Modalities (`modalidad`)\n\nIMSS modality codes describe the worker's affiliation type. Official descriptions preserved in Spanish for legal traceability with the institute.\n\n| `modalidad` | Description |\n| :--- | :--- |\n| `10` | Urban permanent and temporary workers (Trabajadores permanentes y eventuales de la ciudad) |\n| `13` | Rural temporary workers (Trabajadores eventuales del campo) |\n| `14` | Rural permanent workers (Trabajadores permanentes del campo) |\n| `17` | Re-entry rural temporary workers (Reingreso de trabajadores eventuales del campo) |\n| `18` | Re-entry rural permanent workers (Reingreso de trabajadores permanentes del campo) |\n| `30` | Re-entry urban permanent and temporary workers (Reingreso de trabajadores permanentes y eventuales de la ciudad) |\n| `31` | Voluntary continuation in the mandatory regime (Continuación voluntaria al régimen obligatorio) |\n| `32` | Independent workers (Trabajadores independientes) |\n| `33` | Domestic workers (Trabajadores domésticos) |\n| `34` | Federal or state government workers (Trabajadores del gobierno federal o estatal) |\n| `35` | IMSS-affiliated students (Estudiantes afiliados al IMSS) |\n| `36` | Scholarship holders or social programs (Becarios o programas sociales) |\n| `40` | Voluntary continuation in the mandatory regime (alternate) |\n| `42` | Individual employer with domestic workers (Patrón persona física con trabajadores domésticos) |\n| `43` | International organization workers (Trabajadores de organismos internacionales) |\n| `44` | Seasonal or fixed-term workers (Trabajadores por temporada o tiempo determinado) |\n| `45` | Re-entered retirees in mandatory regime (Pensionados reincorporados al régimen obligatorio) |\n| `46` | Construction temporary workers (Trabajadores eventuales de la construcción) |\n| `47` | Trust workers with special regime (Trabajadores de confianza con régimen especial) |\n| `48` | Affiliated municipal public servants (Servidores públicos municipales afiliados) |\n| `50` | Voluntary continuation with extended coverage (Continuación voluntaria con cobertura extendida) |\n| `51` | Voluntary affiliation for students or apprentices (Afiliación voluntaria para estudiantes o aprendices) |\n| `60` | Special social incorporation regime — RESICO (Régimen especial de incorporación social) |\n| `70` | IMSS-Bienestar or community programs modality |\n| `72` | Inter-agency public agreement with IMSS (Convenio entre dependencias públicas y el IMSS) |\n\n#### 5. SAT Article 69 Sub-lists (`listType`)\n\n| `listType` | Sub-list (SAT) | Risk Level |\n| :--- | :--- | :--- |\n| SAT_69_FIRMES | Firmes | MEDIUM |\n| SAT_69_CANCELADOS | Cancelados (Insolvencia, general) | MEDIUM |\n| SAT_69_CANCELADOS_07_15 | Cancelados 2007–2015 (Art. 146-A) | MEDIUM |\n| SAT_69_EXIGIBLES | Exigibles | MEDIUM |\n| SAT_69_NO_LOCALIZADOS | No Localizados | HIGH |\n| SAT_69_CSD_SIN_EFECTOS | Certificados de Sello Digital (CSD) sin Efectos | HIGH |\n| SAT_69_SENTENCIAS | Sentencias | CRITICAL |\n| SAT_69_REDUCCION_74_CFF | Reducción Art. 74 CFF | LOW |\n| SAT_69_CONDONADOS_07_15 | Condonados 2007–2015 (Decreto) | LOW |\n| SAT_69_CONDONADOS_146B_CFF | Condonados Art. 146-B CFF | LOW |\n| SAT_69_CONDONADOS_DECRETO | Condonados por Decreto | LOW |\n| SAT_69_CONDONADOS_21_CFF | Condonados Art. 21 CFF | LOW |\n| SAT_69_RETORNO_INVERSIONES | Retorno de Inversiones | LOW |\n| SAT_69_ENTES_PUBLICOS_OMISOS | Entes Públicos y de Gobierno Omisos | LOW |\n\n#### 6. SAT Article 69-B Status (`complianceDetails.status`)\n\nThe SAT 69-B endpoint always returns `listType: SAT_69B`. The granular state lives in `complianceDetails.status`:\n\n| `status` | Description | Risk Level |\n| :--- | :--- | :--- |\n| PRESUNTO | Currently under investigation for simulated operations (EFOS) | HIGH |\n| DEFINITIVO | Confirmed shell company / EFOS | CRITICAL |\n| DESVIRTUADO | Investigated but successfully proved innocence | LOW |\n| SENTENCIA_FAVORABLE | Won in court / cleared by judicial ruling | LOW |\n\n#### 7. PEPs Categories (`listType`)\n\nThese are OrigoID's stable taxonomy codes. They remain consistent over time so client integrations don't need to change when data sources evolve.\n\n| `listType` | Description | Risk Level |\n| :--- | :--- | :--- |\n| PEP_ACTIVE | Politically Exposed Person — currently in office | HIGH |\n| PEP_INACTIVE | Politically Exposed Person — record marked inactive by the source | MEDIUM |\n| EX_PEP | Former PEP — held office in the past | MEDIUM |\n| PEP_AFFINITY | Family member or close associate of an active PEP | MEDIUM |\n| EX_PEP_AFFINITY | Family member or close associate of a former PEP | LOW |\n\n#### 8. OFAC Lists (`listType`)\n\nWe 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`).\n\n| `listType` | Official OFAC list | Risk Level |\n| :--- | :--- | :--- |\n| OFAC_SDN | Specially Designated Nationals & Blocked Persons | CRITICAL |\n| OFAC_NON_SDN | Consolidated Non-SDN List | HIGH |\n| OFAC_FSE | Foreign Sanctions Evaders | CRITICAL |\n| OFAC_NS_ISA | Non-SDN Iran Sanctions Act List | HIGH |\n| OFAC_SSI | Sectoral Sanctions Identifications List | MEDIUM |\n| OFAC_CAPTA | Foreign Financial Institutions subject to Correspondent / Payable-Through Account Sanctions | HIGH |\n| OFAC_NS_PLC | Non-SDN Palestinian Legislative Council | LOW |\n\n#### 9. CFDI Effect (`effect`)\n\nFiscal purpose of the invoice as classified by SAT. Each CFDI has exactly one effect.\n\n| `effect` | SAT code | Description |\n| :--- | :--- | :--- |\n| INCOME | I (Ingreso) | Sales / revenue invoice. Issuer received payment for goods or services. |\n| EXPENSE | E (Egreso) | Refund, credit note, or discount. Reverses or reduces a previous income invoice. |\n| TRANSPORT | T (Traslado) | Goods transport waybill (Carta Porte). Does not reflect a sale, only movement of goods. |\n| PAYROLL | N (Nómina) | Payroll receipt issued by an employer to an employee. |\n| PAYMENT | P (Pago) | Payment receipt complement (REP) for invoices paid in installments (PPD). |\n\n#### 10. CFDI Status (`status`)\n\nCurrent fiscal status of the CFDI according to SAT's verification service.\n\n| `status` | Description |\n| :--- | :--- |\n| VALID | Vigente. The CFDI is current and fiscally valid. |\n| CANCELED | Cancelada. The CFDI has been canceled and is no longer fiscally valid. |\n\n#### 11. CFDI Cancellation Status (`cancellationStatus`)\n\nReflects 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.\n\n| `cancellationStatus` | Description |\n| :--- | :--- |\n| NOT_CANCELABLE | Cannot be canceled (e.g. payment complements, payroll receipts, or invoices linked to other active CFDIs). |\n| CANCELABLE_WITHOUT_ACCEPTANCE | The issuer may cancel unilaterally (small amounts, payroll corrections, etc.). |\n| CANCELABLE_WITH_ACCEPTANCE | The issuer can request cancellation, but the receiver must accept it within 72 hours. |\n| CANCELED_WITHOUT_ACCEPTANCE | Already canceled; acceptance was not required. |\n| CANCELED_WITH_ACCEPTANCE | Already canceled; the receiver approved the cancellation. |\n\n---\n**Soporte:** contacto@origoid.com", "version": "1.0.0", "contact": { "name": "Soporte OrigoId", "email": "contacto@origoid.com" } }, "servers": [ { "url": "https://api.origoid.com" } ], "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 biometrics: 1:1 face match against identity documents and liveness detection." }, { "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": { "/auth/token": { "post": { "tags": [ "Authentication" ], "summary": "Generate Bearer Token", "description": "**Credits:** Free — authentication endpoint.\n\nIssues a short-lived Bearer JWT from valid API Key or Basic credentials. The token can then be sent as `Authorization: Bearer ` on subsequent requests instead of resending your long-lived API Key. Useful for handing access to a downstream client without sharing your primary credentials.\n\n**Auth:** API Key (`x-api-key`) or HTTP Basic. Bearer tokens cannot issue new tokens (no token chaining).\n\n**Body:** entirely optional. Send `{}` to get a token with default lifetime.\n\n**Lifetime:** controlled by `expireAfter` (seconds). When omitted, the gateway uses its configured default (currently 3600). When present, it must be between 1 and the configured maximum (currently 3600). Values outside that range are rejected with `OUT_OF_RANGE`.\n\n**Revocation:** tokens are stateless and self-expiring. There is no revocation endpoint — if a token is compromised, rotate the underlying API Key. The next snapshot reload propagates the rotation across all gateway instances within ~5 minutes.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "expireAfter": { "type": "integer", "example": 3600, "minimum": 1, "maximum": 3600, "description": "Token lifetime in seconds. Optional. When omitted the gateway uses its configured default (currently 3600). Values outside [1, 3600] are rejected with `OUT_OF_RANGE`." } } }, "examples": { "Default lifetime": { "summary": "Default lifetime", "value": {} }, "Custom lifetime": { "summary": "Custom lifetime", "value": { "expireAfter": 60 } } } } } }, "responses": { "200": { "description": "Token generated successfully.", "content": { "application/json": { "examples": { "Success": { "summary": "Token Generated Successfully", "value": { "status": "OK", "type": "SUCCESS", "message": "Token issued", "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiI...", "token_type": "Bearer", "expires_in": 3600, "scope": "*" }, "transactionId": "3eb33303-3466-4071-872e-067584149666", "processedAt": "2026-03-19T10:00:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The authentication service is currently unavailable", "data": null, "transactionId": "9d4b00fc-6695-47c5-a858-fe50397227c3", "processedAt": "2026-05-21T10:00:00-06:00", "billable": false } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "expireAfter exceeds maximum allowed (3600)", "data": null, "errors": [ { "field": "expireAfter", "code": "OUT_OF_RANGE", "message": "expireAfter must be <= 3600 seconds" }, { "field": "expireAfter", "code": "OUT_OF_RANGE", "message": "expireAfter must be >= 1 second" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "e5a8833d-2b8e-4b7c-9e44-5c54e1800f94", "processedAt": "2026-05-21T10:00:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "91e5aa00-5835-4f09-9511-20a03f508cf8", "processedAt": "2026-05-21T10:00: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 } }, "Bearer Cannot Chain": { "summary": "Bearer Cannot Chain", "value": { "status": "ERROR", "type": "UNAUTHORIZED", "message": "Bearer auth cannot issue new tokens — use api_key or basic", "data": null, "transactionId": "a2c83e91-5cf4-4f27-93ab-9eb8af115e02", "processedAt": "2026-05-21T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "issueToken", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/auth/token \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"expireAfter\": 1800}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/auth/token\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"expireAfter\": 1800\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/auth/token\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"expireAfter\": 1800\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"expireAfter\\\": 1800}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/auth/token\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"expireAfter\": 1800}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/auth/token\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"expireAfter\\\": 1800}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/auth/token\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/renapo/v1/curp-validations": { "post": { "tags": [ "RENAPO" ], "summary": "Validate CURP", "description": "**Credits:** 1 per call.\n\nValidates a CURP (Clave Única de Registro de Población) against the official RENAPO registry and returns the full personal record associated with it: given names, surnames, gender, date of birth, birth state, document status (active, deceased, apocryphal, judicial suspension), and registration metadata.\n\nOptionally generates the associated 13-character RFC (Registro Federal de Contribuyentes) when `generateRfc: true` is sent. RFC generation is deterministic from CURP and does not call SAT.\n\nUse this endpoint when you have a CURP and need to confirm it is genuine, find out who owns it, or detect if the holder is deceased before extending a financial product.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "curp" ], "properties": { "curp": { "type": "string", "example": "TEST900101HDFRRN09", "description": "CURP to validate (18 characters)." }, "generateRfc": { "type": "boolean", "example": true, "description": "Generate RFC associated with the CURP." } } } } } }, "responses": { "200": { "description": "Business Responses (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success without RFC": { "summary": "Success (Without RFC)", "value": { "status": "OK", "type": "SUCCESS", "message": "CURP found and validated", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "AN", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440000", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Success with RFC": { "summary": "Success (With RFC)", "value": { "status": "OK", "type": "SUCCESS", "message": "CURP found and validated", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": "PELJ900101AB7", "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "AN", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440001", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Deceased": { "summary": "Deceased", "value": { "status": "OK", "type": "CURP_DECEASED", "message": "CURP flagged as deceased", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BD", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440030", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Homonymy": { "summary": "Homonymy", "value": { "status": "OK", "type": "CURP_HOMONYMY", "message": "CURP found with homonymy alert", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "AH", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440031", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Apocryphal": { "summary": "Apocryphal", "value": { "status": "OK", "type": "CURP_APOCRYPHAL", "message": "CURP deactivated due to apocryphal document", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BAP", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440032", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Judicial": { "summary": "Judicial", "value": { "status": "OK", "type": "CURP_JUDICIAL_SUSPENSION", "message": "CURP suspended by judicial order", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BJD", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440033", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Inactive": { "summary": "Inactive", "value": { "status": "OK", "type": "CURP_INACTIVE", "message": "CURP exists in RENAPO but was never activated", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BSU", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440037", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Not Found": { "summary": "Not Found", "value": { "status": "OK", "type": "CURP_NOT_FOUND", "message": "CURP not found", "data": null, "transactionId": "550e8400-e29b-41d4-a716-446655440002", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "curp", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'curp'" }, { "field": "curp", "code": "INVALID_FORMAT", "message": "curp is not a valid CURP" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "550e8400-e29b-41d4-a716-446655440004", "processedAt": "2026-03-15T12:35:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The RENAPO service is currently unavailable. Please retry.", "data": null, "transactionId": "550e8400-e29b-41d4-a716-446655440005", "processedAt": "2026-03-15T12:35:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "550e8400-e29b-41d4-a716-446655440006", "processedAt": "2026-03-15T12:35:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Unauthorized (Gateway Error)", "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": "66b18b75-3a29-4143-8d90-77b31cfbbe74", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "validateCurp", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/renapo/v1/curp-validations \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"curp\": \"TEST900101HDFRRN09\", \"generateRfc\": true}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/renapo/v1/curp-validations\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"curp\": \"TEST900101HDFRRN09\",\n \"generateRfc\": true\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/renapo/v1/curp-validations\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"curp\": \"TEST900101HDFRRN09\",\n \"generateRfc\": True\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"curp\\\": \\\"TEST900101HDFRRN09\\\", \\\"generateRfc\\\": true}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/renapo/v1/curp-validations\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"curp\": \"TEST900101HDFRRN09\", \"generateRfc\": true}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/renapo/v1/curp-validations\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"curp\\\": \\\"TEST900101HDFRRN09\\\", \\\"generateRfc\\\": true}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/renapo/v1/curp-validations\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/renapo/v1/curp-lookups": { "post": { "tags": [ "RENAPO" ], "summary": "Retrieve CURP via Demographics", "description": "**Credits:** 2 per call.\n\nReconstructs a CURP from the four official input fields: given names, first surname, second surname, gender, date of birth, and birth state code. Calls RENAPO and returns the matching CURP plus the full personal record (same shape as `validateCurp`).\n\nUse this endpoint when your KYC form collects names and date of birth but not the CURP, and you need the CURP to file a financial product or report to regulators. The lookup uses RENAPO's strict matching — if any field is misspelled, no match is returned (`CURP_NOT_FOUND`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "givenNames", "firstSurname", "dateOfBirth", "gender", "birthStateCode" ], "properties": { "givenNames": { "type": "string", "example": "JUAN" }, "firstSurname": { "type": "string", "example": "PEREZ" }, "secondSurname": { "type": "string", "example": "LOPEZ" }, "dateOfBirth": { "type": "string", "example": "1990-01-01", "description": "Format YYYY-MM-DD" }, "gender": { "type": "string", "enum": [ "H", "M", "X" ], "example": "H" }, "birthStateCode": { "type": "string", "example": "DF" }, "generateRfc": { "type": "boolean", "example": true } } } } } }, "responses": { "200": { "description": "Business Responses (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success without RFC": { "summary": "Success (Without RFC)", "value": { "status": "OK", "type": "SUCCESS", "message": "CURP found and validated", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "AN", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440020", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Success with RFC": { "summary": "Success (With RFC)", "value": { "status": "OK", "type": "SUCCESS", "message": "CURP found and validated", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": "PELJ900101AB7", "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "AN", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440021", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Deceased": { "summary": "Deceased", "value": { "status": "OK", "type": "CURP_DECEASED", "message": "CURP flagged as deceased", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BD", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440030", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Homonymy": { "summary": "Homonymy", "value": { "status": "OK", "type": "CURP_HOMONYMY", "message": "CURP found with homonymy alert", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "AH", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440031", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Apocryphal": { "summary": "Apocryphal", "value": { "status": "OK", "type": "CURP_APOCRYPHAL", "message": "CURP deactivated due to apocryphal document", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BAP", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440032", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Judicial": { "summary": "Judicial", "value": { "status": "OK", "type": "CURP_JUDICIAL_SUSPENSION", "message": "CURP suspended by judicial order", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BJD", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440033", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Inactive": { "summary": "Inactive", "value": { "status": "OK", "type": "CURP_INACTIVE", "message": "CURP exists in RENAPO but was never activated", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BSU", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" } }, "transactionId": "550e8400-e29b-41d4-a716-446655440037", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Not Found": { "summary": "Not Found", "value": { "status": "OK", "type": "CURP_NOT_FOUND", "message": "No CURP matches the provided demographic data", "data": null, "transactionId": "550e8400-e29b-41d4-a716-446655440034", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "givenNames", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'givenNames'" }, { "field": "firstSurname", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'firstSurname'" }, { "field": "gender", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'gender'" }, { "field": "gender", "code": "INVALID_ENUM_VALUE", "message": "gender must be one of: H, M, X" }, { "field": "dateOfBirth", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'dateOfBirth'" }, { "field": "dateOfBirth", "code": "INVALID_FORMAT", "message": "dateOfBirth must be in YYYY-MM-DD format" }, { "field": "birthStateCode", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'birthStateCode'" }, { "field": "birthStateCode", "code": "INVALID_ENUM_VALUE", "message": "birthStateCode is not a valid Mexican state code" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "550e8400-e29b-41d4-a716-446655440022", "processedAt": "2026-03-15T12:35:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The RENAPO service is currently unavailable. Please retry.", "data": null, "transactionId": "550e8400-e29b-41d4-a716-446655440035", "processedAt": "2026-03-15T12:35:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "550e8400-e29b-41d4-a716-446655440036", "processedAt": "2026-03-15T12:35: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": "dbc14fd1-993b-4c6c-8e51-4d16a169e903", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "lookupCurp", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/renapo/v1/curp-lookups \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"givenNames\": \"JUAN\", \"firstSurname\": \"PEREZ\", \"secondSurname\": \"LOPEZ\", \"dateOfBirth\": \"1990-01-01\", \"gender\": \"H\", \"birthStateCode\": \"DF\", \"generateRfc\": true}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/renapo/v1/curp-lookups\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"givenNames\": \"JUAN\",\n \"firstSurname\": \"PEREZ\",\n \"secondSurname\": \"LOPEZ\",\n \"dateOfBirth\": \"1990-01-01\",\n \"gender\": \"H\",\n \"birthStateCode\": \"DF\",\n \"generateRfc\": true\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/renapo/v1/curp-lookups\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"givenNames\": \"JUAN\",\n \"firstSurname\": \"PEREZ\",\n \"secondSurname\": \"LOPEZ\",\n \"dateOfBirth\": \"1990-01-01\",\n \"gender\": \"H\",\n \"birthStateCode\": \"DF\",\n \"generateRfc\": True\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"givenNames\\\": \\\"JUAN\\\", \\\"firstSurname\\\": \\\"PEREZ\\\", \\\"secondSurname\\\": \\\"LOPEZ\\\", \\\"dateOfBirth\\\": \\\"1990-01-01\\\", \\\"gender\\\": \\\"H\\\", \\\"birthStateCode\\\": \\\"DF\\\", \\\"generateRfc\\\": true}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/renapo/v1/curp-lookups\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"givenNames\": \"JUAN\", \"firstSurname\": \"PEREZ\", \"secondSurname\": \"LOPEZ\", \"dateOfBirth\": \"1990-01-01\", \"gender\": \"H\", \"birthStateCode\": \"DF\", \"generateRfc\": true}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/renapo/v1/curp-lookups\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"givenNames\\\": \\\"JUAN\\\", \\\"firstSurname\\\": \\\"PEREZ\\\", \\\"secondSurname\\\": \\\"LOPEZ\\\", \\\"dateOfBirth\\\": \\\"1990-01-01\\\", \\\"gender\\\": \\\"H\\\", \\\"birthStateCode\\\": \\\"DF\\\", \\\"generateRfc\\\": true}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/renapo/v1/curp-lookups\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/renapo/v1/curp-documents": { "post": { "tags": [ "RENAPO" ], "summary": "CURP Official Document (PDF)", "description": "**Credits:** 2 per call.\n\nRetrieves the official RENAPO CURP document (\"Constancia de la CURP\") as a PDF, together with the full validated record and the CURP's RENAPO status — the **same status matrix as `curp-validations`** (active, homonymy, deceased, apocryphal, judicial suspension, inactive). Use it when you need the citizen's official, printable certificate, not just the validated data.\n\nThe PDF is returned **inline as base64** in `data.files[0].content`, alongside the parsed identity fields. This is a **synchronous** call.\n\nOptionally pass `generateRfc: true` to also receive the deterministic `personalInfo.rfc` (computed from the CURP, no SAT call) — identical to `curp-validations`.\n\n**Why it differs from `curp-validations`:** this endpoint retrieves the actual document from RENAPO, so a response takes a little longer to return. It is priced at **2 credits** and has a lower rate limit than the high-volume `curp-validations`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "curp" ], "properties": { "curp": { "type": "string", "description": "The 18-character CURP whose official document is requested.", "example": "TEST900101HDFRRN09" }, "generateRfc": { "type": "boolean", "example": true, "description": "Generate the RFC associated with the CURP. Deterministic from the CURP (no SAT call). When true, `personalInfo.rfc` is included — same as `curp-validations`." } } }, "examples": { "By CURP": { "summary": "By CURP", "value": { "curp": "TEST900101HDFRRN09" } }, "By CURP with RFC": { "summary": "By CURP + RFC generation", "value": { "curp": "TEST900101HDFRRN09", "generateRfc": true } } } } } }, "responses": { "200": { "description": "CURP document result (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success": { "summary": "Success — active CURP, document issued", "value": { "status": "OK", "type": "SUCCESS", "message": "CURP document retrieved", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": "TEST900101AB7", "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "AN", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 48213, "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9...TRUNCATED_BASE64..." } ] }, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-111111111111", "processedAt": "2026-06-01T10:00:00-06:00", "billable": true } }, "Homonymy": { "summary": "CURP_HOMONYMY — active with homonymy alert, document issued", "value": { "status": "OK", "type": "CURP_HOMONYMY", "message": "CURP found with homonymy alert; document issued", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "AH", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 48213, "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9...TRUNCATED_BASE64..." } ] }, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-222222222222", "processedAt": "2026-06-01T10:00:00-06:00", "billable": true } }, "Deceased": { "summary": "CURP_DECEASED — deceased record, document issued", "value": { "status": "OK", "type": "CURP_DECEASED", "message": "CURP flagged as deceased", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BD", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 48213, "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9...TRUNCATED_BASE64..." } ] }, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-333333333333", "processedAt": "2026-06-01T10:00:00-06:00", "billable": true } }, "Apocryphal": { "summary": "CURP_APOCRYPHAL — apocryphal record, document issued", "value": { "status": "OK", "type": "CURP_APOCRYPHAL", "message": "CURP deactivated due to apocryphal document", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BAP", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 48213, "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9...TRUNCATED_BASE64..." } ] }, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-444444444444", "processedAt": "2026-06-01T10:00:00-06:00", "billable": true } }, "Judicial": { "summary": "CURP_JUDICIAL_SUSPENSION — judicially suspended, document issued", "value": { "status": "OK", "type": "CURP_JUDICIAL_SUSPENSION", "message": "CURP suspended by judicial order", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BJD", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 48213, "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9...TRUNCATED_BASE64..." } ] }, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-555555555555", "processedAt": "2026-06-01T10:00:00-06:00", "billable": true } }, "Inactive": { "summary": "CURP_INACTIVE — never activated, document issued", "value": { "status": "OK", "type": "CURP_INACTIVE", "message": "CURP exists in RENAPO but was never activated", "data": { "personalInfo": { "curp": "TEST900101HDFRRN09", "rfc": null, "givenNames": "JUAN", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "gender": "H", "dateOfBirth": "1990-01-01", "birthState": "DISTRITO FEDERAL", "birthStateCode": "DF", "nationality": "MEXICO" }, "documentDetails": { "curpStatus": "BSU", "probatoryDocumentCode": 1 }, "registrationDetails": { "state": "DISTRITO FEDERAL", "stateCode": "09", "municipality": "CUAUHTEMOC", "municipalityCode": "015", "year": "1990", "foreignNumber": "" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 48213, "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9...TRUNCATED_BASE64..." } ] }, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-666666666666", "processedAt": "2026-06-01T10:00:00-06:00", "billable": true } }, "Not Found": { "summary": "CURP_NOT_FOUND", "value": { "status": "OK", "type": "CURP_NOT_FOUND", "message": "CURP not found", "data": null, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-777777777777", "processedAt": "2026-06-01T10:00:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "curp", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'curp'" }, { "field": "curp", "code": "INVALID_FORMAT", "message": "curp must be a valid 18-character CURP" } ], "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-888888888888", "processedAt": "2026-06-01T10:00:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The RENAPO document service is currently unavailable. Please retry.", "data": null, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-999999999999", "processedAt": "2026-06-01T10:00:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-aaaaaaaaaaaa", "processedAt": "2026-06-01T10:00: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": "fb9c33a5-ee2f-42b2-8467-ff6807e14beb", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "extractCurpDocument", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/renapo/v1/curp-documents \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"curp\": \"TEST900101HDFRRN09\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/renapo/v1/curp-documents\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"curp\": \"TEST900101HDFRRN09\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/renapo/v1/curp-documents\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"curp\": \"TEST900101HDFRRN09\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"curp\\\": \\\"TEST900101HDFRRN09\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/renapo/v1/curp-documents\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"curp\": \"TEST900101HDFRRN09\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/renapo/v1/curp-documents\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"curp\\\": \\\"TEST900101HDFRRN09\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/renapo/v1/curp-documents\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/social-security/v1/imss-nss-lookups": { "post": { "tags": [ "Social Security" ], "summary": "Get NSS", "description": "**Credits:** 1 per call.\n\nRetrieves a worker's NSS (Número de Seguridad Social) from IMSS based on CURP. Returns the 11-digit NSS.\n\nUse this endpoint when onboarding employees for payroll or social-security registration: a CURP is far easier to collect than asking the candidate for their NSS card, which is frequently misplaced.\n\n**First-time CURPs:** for a CURP queried for the first time, use [Get NSS (Async)](get-nss-async) — the synchronous lookup can answer `SERVICE_UNAVAILABLE` for it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "curp" ], "properties": { "curp": { "type": "string", "example": "ALMR900805HDFRZA09" } } } } } }, "responses": { "200": { "description": "Business Responses (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success": { "summary": "Success", "value": { "status": "OK", "type": "SUCCESS", "message": "NSS found", "data": { "nss": "92038109713" }, "transactionId": "c5841679-321e-4b05-8d0b-42c457f79e31", "processedAt": "2026-03-15T19:23:00-06:00", "billable": true } }, "No NSS assigned": { "summary": "No NSS Assigned", "value": { "status": "OK", "type": "PERSON_WITHOUT_NSS", "message": "Person has no NSS assigned", "data": null, "transactionId": "31104ee9-32cb-4d99-80c9-38fd1a0cc0bd", "processedAt": "2026-03-15T19:23:00-06:00", "billable": true } }, "Inconsistent Data": { "summary": "Inconsistent Data", "value": { "status": "OK", "type": "IMSS_INCONSISTENT_DATA", "message": "CURP exists but associated data is inconsistent at IMSS", "data": null, "transactionId": "6d6f2145-8521-4276-8b1f-a437beeddfd0", "processedAt": "2026-03-15T19:23:00-06:00", "billable": true } }, "CURP not found": { "summary": "CURP Not Found", "value": { "status": "OK", "type": "CURP_NOT_FOUND", "message": "CURP not found", "data": null, "transactionId": "71bf7c37-74e6-48ee-9e9d-e5c4847be7fe", "processedAt": "2026-03-15T19:23:00-06:00", "billable": true } }, "Operation Limit": { "summary": "Operation Limit", "value": { "status": "OK", "type": "IMSS_OPERATION_LIMIT", "message": "IMSS daily limit reached", "data": null, "transactionId": "53124f18-ef45-4628-8a92-169bc9a72965", "processedAt": "2026-03-15T19:23:00-06:00", "billable": true } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "IMSS service is currently unavailable", "data": null, "transactionId": "5059284d-ff9c-412e-bc4d-32c00c276462", "processedAt": "2026-03-15T19:23:00-06:00", "billable": false } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "curp", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'curp'" }, { "field": "curp", "code": "INVALID_FORMAT", "message": "Invalid CURP format" } ], "transactionId": "d1e3c429-2164-4115-9861-dd1038f55b95", "processedAt": "2026-03-15T19:23:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "463f1f4d-6fab-4206-8dd3-2f0bd2e4d79e", "processedAt": "2026-03-15T19:23: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": "433efac0-250a-4f28-bc0c-0a03108f09f9", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "lookupImssNss", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/social-security/v1/imss-nss-lookups \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"curp\": \"ALMR900805HDFRZA09\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/social-security/v1/imss-nss-lookups\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"curp\": \"ALMR900805HDFRZA09\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/social-security/v1/imss-nss-lookups\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"curp\": \"ALMR900805HDFRZA09\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"curp\\\": \\\"ALMR900805HDFRZA09\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/social-security/v1/imss-nss-lookups\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"curp\": \"ALMR900805HDFRZA09\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/social-security/v1/imss-nss-lookups\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"curp\\\": \\\"ALMR900805HDFRZA09\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/social-security/v1/imss-nss-lookups\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/social-security/v1/imss-nss-lookup-async": { "post": { "tags": [ "Social Security" ], "summary": "Get NSS (Async)", "description": "**Credits:** 2 per resolved request — charged when the result resolves; the `ACCEPTED` acknowledgement is free.\n\nAsynchronous version of **Get NSS**: retrieves a worker's NSS (Número de Seguridad Social) from IMSS based on CURP and delivers the result to your webhook instead of keeping the HTTP request open.\n\n**Immediate response:** `ACCEPTED` with the `transactionId`, or `INVALID_REQUEST` if the request is not valid.\n\n**Result:** delivered to your webhook with the same result types as **Get NSS** (except `INVALID_REQUEST`, which is returned immediately). Every result type, with its example, is in the [Webhooks guide](../../webhooks#get-nss-async).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "curp", "webhook" ], "properties": { "curp": { "type": "string", "description": "18-character CURP.", "example": "ALMR900805HDFRZA09" }, "webhook": { "type": "object", "description": "Where the result of an asynchronous request is delivered (HTTP POST with a JSON body).", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public http or https URL that receives the result.", "example": "https://your-domain.com/hooks/origoid" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional header names and values added to the webhook request (e.g. your own authorization token).", "example": { "Authorization": "Bearer YOUR_WEBHOOK_TOKEN" } } } } } } } } }, "responses": { "200": { "description": "Immediate response (Strict Envelope Pattern). The result is delivered to your webhook.", "content": { "application/json": { "examples": { "Accepted": { "summary": "Accepted", "value": { "status": "OK", "type": "ACCEPTED", "message": "Request accepted, result will be sent to the webhook", "data": null, "transactionId": "39b972d3-20a8-539a-acfb-70657588df9b", "processedAt": "2026-03-15T19:22:30-06:00", "billable": false } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "curp", "code": "INVALID_FORMAT", "message": "curp is not a valid CURP" }, { "field": "webhook", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'webhook'" } ], "transactionId": "6f3f94f7-367d-5434-9af6-41e4ae1954f3", "processedAt": "2026-10-26T11:20:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "IMSS service is currently unavailable", "data": null, "transactionId": "b5885ee2-8cd3-5380-a0b1-18099dbf5dc1", "processedAt": "2026-10-26T11:20:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "6963925a-238e-5ec1-b30a-12692e207926", "processedAt": "2026-10-26T11:20: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": "433efac0-250a-4f28-bc0c-0a03108f09f9", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "createImssNssLookupAsync", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"curp\": \"ALMR900805HDFRZA09\", \"webhook\": {\"url\": \"https://your-domain.com/hooks/origoid\"}}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"curp\": \"ALMR900805HDFRZA09\",\n \"webhook\": {\n \"url\": \"https://your-domain.com/hooks/origoid\"\n }\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"curp\": \"ALMR900805HDFRZA09\",\n \"webhook\": {\n \"url\": \"https://your-domain.com/hooks/origoid\"\n }\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"curp\\\": \\\"ALMR900805HDFRZA09\\\", \\\"webhook\\\": {\\\"url\\\": \\\"https://your-domain.com/hooks/origoid\\\"}}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"curp\": \"ALMR900805HDFRZA09\", \"webhook\": {\"url\": \"https://your-domain.com/hooks/origoid\"}}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"curp\\\": \\\"ALMR900805HDFRZA09\\\", \\\"webhook\\\": {\\\"url\\\": \\\"https://your-domain.com/hooks/origoid\\\"}}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/social-security/v1/imss-employment-status": { "post": { "tags": [ "Social Security" ], "summary": "Employment Status", "description": "**Credits:** 1 per call.\n\nReturns the current IMSS employment status of a worker (identified by CURP + NSS): whether they are currently registered as employed, inactive (no current registration), the modality of registration, the registered employer's RFC, employer name, state, base salary, contributed days, and the period the IMSS report covers.\n\nUse this endpoint for income verification (lending, leasing), employment confirmation (background checks), or to detect overlapping employment when complying with employment regulations.\n\nSet `includePdf: true` to also receive the official IMSS report as a PDF in `data.files[]` (`kind: document`, base64) — no extra credits. `reportDetails` describes that report: `reportPeriod` (month the report covers), `issueDate`, `currentMonth` (current month according to IMSS, the month of `issueDate`) and `nextReportMonth` (month in which IMSS will publish the next report).\n\n**First-time CURPs:** for a CURP queried for the first time, use [Employment Status (Async)](employment-status-async) — the synchronous lookup can answer `SERVICE_UNAVAILABLE` for it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "curp", "nss" ], "properties": { "curp": { "type": "string", "example": "GARM900101HDFRZA01" }, "nss": { "type": "string", "example": "92038109713" }, "includePdf": { "type": "boolean", "default": false, "description": "Also return the official IMSS report as a PDF in `data.files[]`. No extra credits." } } } } } }, "responses": { "200": { "description": "Business Responses (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Active Employment": { "summary": "Active Employment", "value": { "status": "OK", "type": "SUCCESS", "message": "Active employment found", "data": { "nss": "92038109713", "personalInfo": { "curp": "GARM900101HDFRZA01", "givenNames": "SANTIAGO FORTINO", "firstSurname": "ESPINOZA", "secondSurname": "SANCHEZ", "gender": "H" }, "employmentInformation": [ { "employerRegistration": "Y5473416", "modality": "10", "employerRfc": "FDM020722442", "employerName": "LOGISTICA GLOBAL DE MEXICO S DE RL DE CV", "state": "CIUDAD DE MEXICO", "stateCode": "09", "baseSalary": { "amount": "2932.75", "currency": "MXN" }, "contributedDays": 28 } ], "reportDetails": { "reportPeriod": "2026-02", "issueDate": "2026-03-15", "currentMonth": "2026-03", "nextReportMonth": "2026-04" } }, "transactionId": "26aca817-9a02-4119-bc06-2fcab3666454", "processedAt": "2026-03-15T19:24:00-06:00", "billable": true } }, "Active Employment with PDF": { "summary": "Active Employment with PDF", "value": { "status": "OK", "type": "SUCCESS", "message": "Active employment found", "data": { "nss": "92038109713", "personalInfo": { "curp": "GARM900101HDFRZA01", "givenNames": "SANTIAGO FORTINO", "firstSurname": "ESPINOZA", "secondSurname": "SANCHEZ", "gender": "H" }, "employmentInformation": [ { "employerRegistration": "Y5473416", "modality": "10", "employerRfc": "FDM020722442", "employerName": "LOGISTICA GLOBAL DE MEXICO S DE RL DE CV", "state": "CIUDAD DE MEXICO", "stateCode": "09", "baseSalary": { "amount": "2932.75", "currency": "MXN" }, "contributedDays": 28 } ], "reportDetails": { "reportPeriod": "2026-02", "issueDate": "2026-03-15", "currentMonth": "2026-03", "nextReportMonth": "2026-04" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 19219, "content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoK..." } ] }, "transactionId": "7a940f62-d5ca-5b9a-9c16-5bd1c6d8a1fd", "processedAt": "2026-03-15T19:24:00-06:00", "billable": true } }, "Inactive Employment": { "summary": "Inactive Employment", "value": { "status": "OK", "type": "INACTIVE_EMPLOYMENT", "message": "No active employment found", "data": { "nss": "07774410915", "personalInfo": { "curp": "VIRD881122MDFRZS04", "givenNames": "DIANA PATRICIA", "firstSurname": "VILLALOBOS", "secondSurname": "RIVERA", "gender": "M" }, "employmentInformation": [], "reportDetails": { "reportPeriod": "2026-02", "issueDate": "2026-03-15", "currentMonth": "2026-03", "nextReportMonth": "2026-04" } }, "transactionId": "e89107c6-5a4f-4386-be31-83a87c3fdf05", "processedAt": "2026-03-15T19:24:00-06:00", "billable": true } }, "Mismatch CURP NSS": { "summary": "Mismatch CURP NSS", "value": { "status": "OK", "type": "MISMATCH_CURP_NSS", "message": "CURP and NSS do not match", "data": null, "transactionId": "fe0d7afe-453c-4b3d-b06d-2d2a3fafab66", "processedAt": "2026-03-15T19:24:00-06:00", "billable": true } }, "CURP not found": { "summary": "CURP Not Found", "value": { "status": "OK", "type": "CURP_NOT_FOUND", "message": "CURP not found in IMSS", "data": null, "transactionId": "2ae7dcdf-b4c9-4d35-bbaa-578febe90302", "processedAt": "2026-03-15T19:24:00-06:00", "billable": true } }, "Person without NSS": { "summary": "Person Without NSS", "value": { "status": "OK", "type": "PERSON_WITHOUT_NSS", "message": "Person exists at IMSS but has no own NSS assigned", "data": null, "transactionId": "cbb811ef-d9ac-5684-9c65-ae49734da9db", "processedAt": "2026-03-15T19:24:00-06:00", "billable": true } }, "Inconsistent Data": { "summary": "Inconsistent Data", "value": { "status": "OK", "type": "IMSS_INCONSISTENT_DATA", "message": "CURP exists but associated data is inconsistent at IMSS", "data": null, "transactionId": "734fc034-0b47-48a1-b3ab-c7ccbe5e3f80", "processedAt": "2026-03-15T19:24:00-06:00", "billable": true } }, "Operation Limit": { "summary": "Operation Limit", "value": { "status": "OK", "type": "IMSS_OPERATION_LIMIT", "message": "IMSS daily limit reached", "data": null, "transactionId": "8e6e47de-50b4-47f7-a759-10b45d2d6d7b", "processedAt": "2026-03-15T19:24:00-06:00", "billable": true } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "IMSS service is currently unavailable", "data": null, "transactionId": "de85d0ae-5e1e-4d38-b638-1e4f5e5b66c7", "processedAt": "2026-03-15T19:24:00-06:00", "billable": false } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "curp", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'curp'" }, { "field": "nss", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'nss'" }, { "field": "curp", "code": "INVALID_FORMAT", "message": "Invalid CURP format" }, { "field": "nss", "code": "INVALID_FORMAT", "message": "Invalid NSS format (must be 11 digits)" } ], "transactionId": "d9346a9b-e83a-40a6-bbdb-87fc70090e83", "processedAt": "2026-03-15T19:24:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "fc6243bf-3d66-4b3c-a2ca-f55c9bbb0a60", "processedAt": "2026-03-15T19:24: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": "26a32ffc-252c-4571-8c63-9836f3f4e095", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "getImssEmploymentStatus", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/social-security/v1/imss-employment-status \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"curp\": \"GARM900101HDFRZA01\", \"nss\": \"92038109713\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/social-security/v1/imss-employment-status\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"curp\": \"GARM900101HDFRZA01\",\n \"nss\": \"92038109713\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/social-security/v1/imss-employment-status\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"curp\": \"GARM900101HDFRZA01\",\n \"nss\": \"92038109713\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"curp\\\": \\\"GARM900101HDFRZA01\\\", \\\"nss\\\": \\\"92038109713\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/social-security/v1/imss-employment-status\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"curp\": \"GARM900101HDFRZA01\", \"nss\": \"92038109713\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/social-security/v1/imss-employment-status\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"curp\\\": \\\"GARM900101HDFRZA01\\\", \\\"nss\\\": \\\"92038109713\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/social-security/v1/imss-employment-status\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/social-security/v1/imss-employment-status-async": { "post": { "tags": [ "Social Security" ], "summary": "Employment Status (Async)", "description": "**Credits:** 2 per resolved request — charged when the result resolves; the `ACCEPTED` acknowledgement is free. `includePdf` adds no extra credits.\n\nAsynchronous version of **Employment Status**: returns the current IMSS employment status of a worker identified by CURP and delivers the result to your webhook instead of keeping the HTTP request open.\n\n`nss` is optional: when you send it, it is checked against the NSS registered for the CURP and a difference returns `MISMATCH_CURP_NSS`. Set `includePdf: true` to also receive the official IMSS report as a PDF in `data.files[]`.\n\n**Immediate response:** `ACCEPTED` with the `transactionId`, or `INVALID_REQUEST` if the request is not valid.\n\n**Result:** delivered to your webhook with the same result types and `data` as **Employment Status** (except `INVALID_REQUEST`, which is returned immediately). Every result type, with its example, is in the [Webhooks guide](../../webhooks#employment-status-async).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "curp", "webhook" ], "properties": { "curp": { "type": "string", "description": "18-character CURP.", "example": "GARM900101HDFRZA01" }, "nss": { "type": "string", "pattern": "^\\d{11}$", "description": "Optional 11-digit NSS, checked against the NSS registered for the CURP.", "example": "92038109713" }, "includePdf": { "type": "boolean", "default": false, "description": "Also return the official IMSS report as a PDF in `data.files[]`. No extra credits." }, "webhook": { "type": "object", "description": "Where the result of an asynchronous request is delivered (HTTP POST with a JSON body).", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public http or https URL that receives the result.", "example": "https://your-domain.com/hooks/origoid" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional header names and values added to the webhook request (e.g. your own authorization token).", "example": { "Authorization": "Bearer YOUR_WEBHOOK_TOKEN" } } } } } } } } }, "responses": { "200": { "description": "Immediate response (Strict Envelope Pattern). The result is delivered to your webhook.", "content": { "application/json": { "examples": { "Accepted": { "summary": "Accepted", "value": { "status": "OK", "type": "ACCEPTED", "message": "Request accepted, result will be sent to the webhook", "data": null, "transactionId": "322e6c8b-0124-5c84-95db-4da04842d0da", "processedAt": "2026-03-15T19:23:30-06:00", "billable": false } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "curp", "code": "INVALID_FORMAT", "message": "curp is not a valid CURP" }, { "field": "nss", "code": "INVALID_FORMAT", "message": "Invalid NSS format (must be 11 digits)" }, { "field": "webhook", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'webhook'" } ], "transactionId": "6117e20e-ea53-5424-87a9-da7576d4cd12", "processedAt": "2026-10-26T11:20:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "IMSS service is currently unavailable", "data": null, "transactionId": "83c3d081-6906-5b7f-bd17-068e8d0c6200", "processedAt": "2026-10-26T11:20:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "49767ecd-211e-56e8-bda0-bb9cd8b11e92", "processedAt": "2026-10-26T11:20: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": "433efac0-250a-4f28-bc0c-0a03108f09f9", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "createImssEmploymentStatusAsync", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/social-security/v1/imss-employment-status-async \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"curp\": \"GARM900101HDFRZA01\", \"nss\": \"92038109713\", \"includePdf\": true, \"webhook\": {\"url\": \"https://your-domain.com/hooks/origoid\"}}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/social-security/v1/imss-employment-status-async\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"curp\": \"GARM900101HDFRZA01\",\n \"nss\": \"92038109713\",\n \"includePdf\": true,\n \"webhook\": {\n \"url\": \"https://your-domain.com/hooks/origoid\"\n }\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/social-security/v1/imss-employment-status-async\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"curp\": \"GARM900101HDFRZA01\",\n \"nss\": \"92038109713\",\n \"includePdf\": True,\n \"webhook\": {\n \"url\": \"https://your-domain.com/hooks/origoid\"\n }\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"curp\\\": \\\"GARM900101HDFRZA01\\\", \\\"nss\\\": \\\"92038109713\\\", \\\"includePdf\\\": true, \\\"webhook\\\": {\\\"url\\\": \\\"https://your-domain.com/hooks/origoid\\\"}}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/social-security/v1/imss-employment-status-async\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"curp\": \"GARM900101HDFRZA01\", \"nss\": \"92038109713\", \"includePdf\": true, \"webhook\": {\"url\": \"https://your-domain.com/hooks/origoid\"}}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/social-security/v1/imss-employment-status-async\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"curp\\\": \\\"GARM900101HDFRZA01\\\", \\\"nss\\\": \\\"92038109713\\\", \\\"includePdf\\\": true, \\\"webhook\\\": {\\\"url\\\": \\\"https://your-domain.com/hooks/origoid\\\"}}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/social-security/v1/imss-employment-status-async\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/social-security/v1/imss-contribution-weeks": { "post": { "tags": [ "Social Security" ], "summary": "Contribution Weeks", "description": "**Credits:** 3 per resolved request — charged when the result resolves; the `ACCEPTED` acknowledgement and **Contribution Weeks Result** are free.\n\nRetrieves a worker's official IMSS **Certificate of Contributed Weeks** (*Constancia de Semanas Cotizadas*) from their CURP: the official PDF issued by IMSS (with folio and digital seal), the full employment history parsed into JSON, and signals derived from that history (tenure, stability, salary evolution).\n\n**Immediate response:** `ACCEPTED` with the `transactionId`, or `INVALID_REQUEST` if the request is not valid.\n\n**Result:** delivered to your webhook. If your webhook could not receive it, you can fetch it for 24 hours with **Contribution Weeks Result**. Every result type, with its example, and how to read `data`, are in the [Webhooks guide](../../webhooks#contribution-weeks).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "curp", "webhook" ], "properties": { "curp": { "type": "string", "description": "18-character CURP.", "example": "RATL850312HDFMRS07" }, "webhook": { "type": "object", "description": "Where the result of an asynchronous request is delivered (HTTP POST with a JSON body).", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public http or https URL that receives the result.", "example": "https://your-domain.com/hooks/origoid" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional header names and values added to the webhook request (e.g. your own authorization token).", "example": { "Authorization": "Bearer YOUR_WEBHOOK_TOKEN" } } } } } } } } }, "responses": { "200": { "description": "Immediate response (Strict Envelope Pattern). The result is delivered to your webhook.", "content": { "application/json": { "examples": { "Accepted": { "summary": "Accepted", "value": { "status": "OK", "type": "ACCEPTED", "message": "Request accepted, result will be sent to the webhook", "data": null, "transactionId": "975cf12f-f270-51cc-9037-d710134940c9", "processedAt": "2026-08-13T11:17:04-06:00", "billable": false } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "curp", "code": "INVALID_FORMAT", "message": "curp is not a valid CURP" }, { "field": "webhook", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'webhook'" } ], "transactionId": "1af66183-73c5-54d8-b4db-b5e62f5a6025", "processedAt": "2026-10-26T11:20:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "IMSS service is currently unavailable", "data": null, "transactionId": "ddeb6065-5fe1-5a73-9fc8-0164e1c97c8a", "processedAt": "2026-10-26T11:20:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "595881db-ff9c-5c9d-97fb-16a4a3c20326", "processedAt": "2026-10-26T11:20: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": "433efac0-250a-4f28-bc0c-0a03108f09f9", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "createImssContributionWeeks", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"curp\": \"RATL850312HDFMRS07\", \"webhook\": {\"url\": \"https://your-domain.com/hooks/origoid\", \"headers\": {\"Authorization\": \"Bearer YOUR_WEBHOOK_TOKEN\"}}}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"curp\": \"RATL850312HDFMRS07\",\n \"webhook\": {\n \"url\": \"https://your-domain.com/hooks/origoid\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_WEBHOOK_TOKEN\"\n }\n }\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"curp\": \"RATL850312HDFMRS07\",\n \"webhook\": {\n \"url\": \"https://your-domain.com/hooks/origoid\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_WEBHOOK_TOKEN\"\n }\n }\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"curp\\\": \\\"RATL850312HDFMRS07\\\", \\\"webhook\\\": {\\\"url\\\": \\\"https://your-domain.com/hooks/origoid\\\", \\\"headers\\\": {\\\"Authorization\\\": \\\"Bearer YOUR_WEBHOOK_TOKEN\\\"}}}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"curp\": \"RATL850312HDFMRS07\", \"webhook\": {\"url\": \"https://your-domain.com/hooks/origoid\", \"headers\": {\"Authorization\": \"Bearer YOUR_WEBHOOK_TOKEN\"}}}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"curp\\\": \\\"RATL850312HDFMRS07\\\", \\\"webhook\\\": {\\\"url\\\": \\\"https://your-domain.com/hooks/origoid\\\", \\\"headers\\\": {\\\"Authorization\\\": \\\"Bearer YOUR_WEBHOOK_TOKEN\\\"}}}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/social-security/v1/imss-contribution-weeks-results": { "post": { "tags": [ "Social Security" ], "summary": "Contribution Weeks Result", "description": "**Credits:** 0 (free).\n\nFallback to fetch the result of a **Contribution Weeks** request when your webhook could not receive it. Results are available for **24 hours** after the request resolved. The result is always sent to your webhook, so use this endpoint only as a fallback, not to poll.\n\nSend the `transactionId` returned by Contribution Weeks:\n\n- `RESULT_FOUND`: `data` contains the original result envelope, exactly as delivered to the webhook, with its own `transactionId` (the one that was charged). The outer envelope describes this free query.\n- `RESULT_PENDING`: the request is still being processed; the result will be sent to your webhook.\n- `RESULT_EXPIRED`: more than 24 hours have passed; the result is no longer available.\n- `INVALID_REQUEST`: the `transactionId` does not exist or belongs to another client (both answer the same way).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transactionId" ], "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "The `transactionId` returned by Contribution Weeks.", "example": "975cf12f-f270-51cc-9037-d710134940c9" } } } } } }, "responses": { "200": { "description": "Business Responses (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Result Found": { "summary": "Result Found", "value": { "status": "OK", "type": "RESULT_FOUND", "message": "Result found", "data": { "status": "OK", "type": "SUCCESS", "message": "Active employment found", "data": { "nss": "45028712309", "personalInfo": { "curp": "RATL850312HDFMRS07", "givenNames": "LUIS ALBERTO", "firstSurname": "RAMIREZ", "secondSurname": "TORRES", "gender": "H", "dateOfBirth": "1985-03-12" }, "contributionWeeks": { "total": 612, "contributed": 612, "discounted": 0, "reinstated": 0 }, "derivedSignals": { "currentStatus": { "employed": true, "monthsInCurrentStatus": 60, "lastDailySalary": { "amount": "685.50", "currency": "MXN" }, "lastMonthlySalary": { "amount": "20866.62", "currency": "MXN" }, "salaryAtLegalCap": false }, "jobTenure": { "currentJobMonths": 60, "averageJobMonths": 42, "longestJobMonths": 60, "shortestJobMonths": 4.5, "monthsSinceFirstJob": 210 }, "stability": { "employerCount": 4, "distinctEmployerCount": 4, "monthsPerEmployer": 52.5, "jobChanges": 3, "jobChangesLast5Years": 1, "simultaneousJobsDetected": 0, "unemploymentPeriods": { "count": 3, "totalMonths": 22, "longestMonths": 11.5, "monthsSinceLastUnemployment": 60 }, "monthsActuallyEmployed": 188, "percentOfTimeEmployed": 89.5 }, "salary": { "first": { "amount": "210.00", "currency": "MXN" }, "latest": { "amount": "685.50", "currency": "MXN" }, "highest": { "amount": "685.50", "currency": "MXN" }, "lowest": { "amount": "210.00", "currency": "MXN" }, "changePercentFirstToLatest": 226.4, "firstMonthly": { "amount": "6392.40", "currency": "MXN" }, "latestMonthly": { "amount": "20866.62", "currency": "MXN" }, "employerChanges": { "withRaise": 3, "withCut": 0 }, "snapshots": { "oneYearAgo": { "dailySalary": { "amount": "685.50", "currency": "MXN" }, "monthlySalary": { "amount": "20866.62", "currency": "MXN" }, "changePercentToLatest": 0 }, "threeYearsAgo": { "dailySalary": { "amount": "620.00", "currency": "MXN" }, "monthlySalary": { "amount": "18872.80", "currency": "MXN" }, "changePercentToLatest": 10.6 }, "fiveYearsAgo": { "dailySalary": { "amount": "480.00", "currency": "MXN" }, "monthlySalary": { "amount": "14611.20", "currency": "MXN" }, "changePercentToLatest": 42.8 } } }, "salaryTimeline": [ { "event": "HIRED", "date": "2009-02-10", "employerName": "ABARROTES EL SURTIDOR", "dailySalary": { "amount": "210.00", "currency": "MXN" }, "monthlySalary": { "amount": "6392.40", "currency": "MXN" } }, { "event": "TERMINATED", "date": "2009-06-28", "employerName": "ABARROTES EL SURTIDOR", "dailySalary": { "amount": "210.00", "currency": "MXN" }, "monthlySalary": { "amount": "6392.40", "currency": "MXN" } }, { "event": "HIRED", "date": "2021-08-16", "employerName": "SERVICIOS INTEGRALES DEL NORTE SA DE CV", "dailySalary": { "amount": "685.50", "currency": "MXN" }, "monthlySalary": { "amount": "20866.62", "currency": "MXN" } } ] }, "employmentHistory": [ { "employerName": "SERVICIOS INTEGRALES DEL NORTE SA DE CV", "employerRegistration": "A5512340987", "state": "CIUDAD DE MÉXICO", "startDate": "2021-08-16", "endDate": null, "baseSalary": { "amount": "685.50", "currency": "MXN" } }, { "employerName": "DISTRIBUIDORA GAMMA SA DE CV", "employerRegistration": "B7788990011", "state": "JALISCO", "startDate": "2016-05-02", "endDate": "2021-06-30", "baseSalary": { "amount": "540.00", "currency": "MXN" } }, { "employerName": "ABARROTES EL SURTIDOR", "employerRegistration": "C4433221100", "state": "JALISCO", "startDate": "2009-02-10", "endDate": "2009-06-28", "baseSalary": { "amount": "210.00", "currency": "MXN" } } ], "reportDetails": { "source": "IMSS", "documentType": "CONSTANCIA DE SEMANAS COTIZADAS", "folio": "20481135900274651093824", "issueDate": "2026-08-12", "serialNumber": "00000000000000004821", "notarialSequence": "b28f4c19-6a03-41e2-9c15-7dd0a2e51b47", "digitalSeal": "Qm9ndXNTZWFsRXhhbXBsZURhdGFOb3RSZWFsRm9yRG9jdW1lbnRhdGlvbk9ubHk9PQ==" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 73412, "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9GaWx0ZXIvRmxhdGVEZWNvZGUvTGVuZ3Ro..." } ] }, "transactionId": "975cf12f-f270-51cc-9037-d710134940c9", "processedAt": "2026-08-13T11:20:00-06:00", "billable": true }, "transactionId": "c87b960c-1d21-5a39-ac95-c68e05023ee1", "processedAt": "2026-08-13T11:35:00-06:00", "billable": false } }, "Result Pending": { "summary": "Result Pending", "value": { "status": "OK", "type": "RESULT_PENDING", "message": "Result not ready yet, it will be sent to the webhook", "data": null, "transactionId": "8420d7d8-4e51-57e9-9578-f88d2bfd10b9", "processedAt": "2026-08-13T11:18:00-06:00", "billable": false } }, "Result Expired": { "summary": "Result Expired", "value": { "status": "OK", "type": "RESULT_EXPIRED", "message": "Result expired, results are available for 24 hours", "data": null, "transactionId": "c85061c5-780f-5e45-b0fb-c3dc568f0586", "processedAt": "2026-08-14T15:00:00-06:00", "billable": false } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "transactionId", "code": "INVALID_VALUE", "message": "transactionId not found" } ], "transactionId": "b5286080-516e-519e-9b7b-359bc6c40cbd", "processedAt": "2026-10-26T11:20:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "IMSS service is currently unavailable", "data": null, "transactionId": "f3139731-13d7-53ed-bed5-9352e026b4bd", "processedAt": "2026-10-26T11:20:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "dceba039-69b7-5a03-8f19-f9d97a2b1c35", "processedAt": "2026-10-26T11:20: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": "433efac0-250a-4f28-bc0c-0a03108f09f9", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "getImssContributionWeeksResult", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks-results \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"transactionId\": \"975cf12f-f270-51cc-9037-d710134940c9\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks-results\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"transactionId\": \"975cf12f-f270-51cc-9037-d710134940c9\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks-results\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"transactionId\": \"975cf12f-f270-51cc-9037-d710134940c9\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"transactionId\\\": \\\"975cf12f-f270-51cc-9037-d710134940c9\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks-results\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"transactionId\": \"975cf12f-f270-51cc-9037-d710134940c9\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks-results\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"transactionId\\\": \\\"975cf12f-f270-51cc-9037-d710134940c9\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks-results\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/id/v1/voter-list-validations": { "post": { "tags": [ "INE" ], "summary": "Validate Voter List", "description": "**Credits:** 1 per call.\n\nValidates that a Mexican voter ID (INE / IFE) credential exists in INE's Lista Nominal — the official roll of registered voters — by sending CIC, OCR or ID number depending on the credential model. Returns a confirmation, the voter's polling section, and validity dates.\n\nUse this endpoint as part of KYC to verify that the voter ID presented by your customer is registered and valid (not stolen, not lost, not cancelled).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cic" ], "properties": { "cic": { "type": "string", "example": "123456789", "description": "Credential Identification Code (9 digits, back)" }, "citizenIdentifier": { "type": "string", "example": "987654321", "description": "Citizen Identifier (9 digits, back, Models E/E+)" }, "ocr": { "type": "string", "example": "0123456789012", "description": "OCR (13 digits, back, Model D)" } }, "oneOf": [ { "required": [ "citizenIdentifier" ] }, { "required": [ "ocr" ] } ] } } } }, "responses": { "200": { "description": "Business Responses (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Valid Voter": { "summary": "Valid Voter", "value": { "status": "OK", "type": "VALID_VOTER", "message": "INE valid and active for voting", "data": { "isValid": true, "personalInfo": { "electorKey": "GOMEZJ80010112H300" }, "electoralGeography": { "federalDistrict": "12", "localDistrict": "5" }, "validity": { "registrationYear": "2000", "emissionYear": "2023", "validUntilYear": "2033", "emissionNumber": "05" }, "security": { "cic": "123456789", "ocr": "1234567890123" }, "validationStatus": { "stolenReport": null, "officialMessage": "Está vigente como medio de identificación y puede votar" } }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789001", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Foreign Voter": { "summary": "Foreign Voter", "value": { "status": "OK", "type": "VALID_FOREIGN_VOTER", "message": "INE valid for foreign voting", "data": { "isValid": true, "personalInfo": { "electorKey": "GOMEZJ80010112H300" }, "electoralGeography": { "federalDistrict": "12", "localDistrict": "5" }, "validity": { "registrationYear": "2000", "emissionYear": "2023", "validUntilYear": "2033", "emissionNumber": "05" }, "security": { "cic": "123456789", "ocr": "1234567890123" }, "validationStatus": { "stolenReport": null, "officialMessage": "Datos en padrón y credencial vigente para votar desde el extranjero" } }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789002", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Id Only": { "summary": "ID Only", "value": { "status": "OK", "type": "VALID_AS_ID_ONLY", "message": "INE valid as ID only", "data": { "isValid": true, "personalInfo": { "electorKey": "GOMEZJ80010112H300" }, "electoralGeography": { "federalDistrict": "12", "localDistrict": "5" }, "validity": { "registrationYear": "2000", "emissionYear": "2023", "validUntilYear": "2033", "emissionNumber": "05" }, "security": { "cic": "123456789", "ocr": "1234567890123" }, "validationStatus": { "stolenReport": null, "officialMessage": "Vigente solo como medio de identificación con fotografía" } }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789003", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Stolen or Lost": { "summary": "Stolen or Lost", "value": { "status": "OK", "type": "REPORTED_AS_STOLEN_OR_LOST", "message": "INE reported as stolen or lost", "data": { "isValid": false, "personalInfo": { "electorKey": "GOMEZJ80010112H300" }, "electoralGeography": { "federalDistrict": "12", "localDistrict": "5" }, "validity": { "registrationYear": "2000", "emissionYear": "2023", "validUntilYear": "2033", "emissionNumber": "05" }, "security": { "cic": "123456789", "ocr": "1234567890123" }, "validationStatus": { "stolenReport": "1935438", "officialMessage": "La credencial cuenta con un reporte de robo o extravío" } }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789004", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Not Valid": { "summary": "Not Valid", "value": { "status": "OK", "type": "INE_NOT_VALID", "message": "INE not valid for voting", "data": { "isValid": false, "personalInfo": { "electorKey": "GOMEZJ80010112H300" }, "electoralGeography": { "federalDistrict": "12", "localDistrict": "5" }, "validity": { "registrationYear": "2000", "emissionYear": "2023", "validUntilYear": "2033", "emissionNumber": "05" }, "security": { "cic": "123456789", "ocr": "1234567890123" }, "validationStatus": { "stolenReport": null, "officialMessage": "No está vigente como medio de identificación ni puedes votar" } }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789005", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Suspended Judicial": { "summary": "Suspended Judicial", "value": { "status": "OK", "type": "SUSPENDED_BY_JUDICIAL_ORDER", "message": "INE suspended by judicial order", "data": { "isValid": false, "personalInfo": { "electorKey": "GOMEZJ80010112H300" }, "electoralGeography": { "federalDistrict": "12", "localDistrict": "5" }, "validity": { "registrationYear": "2000", "emissionYear": "2023", "validUntilYear": "2033", "emissionNumber": "05" }, "security": { "cic": "123456789", "ocr": "1234567890123" }, "validationStatus": { "stolenReport": null, "officialMessage": "Por mandato judicial has sido suspendido en tus derechos" } }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789006", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Not Found": { "summary": "Not Found", "value": { "status": "OK", "type": "INE_NOT_FOUND", "message": "INE credential not found in the nominal list", "data": { "isValid": false }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789007", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Mismatched OCR": { "summary": "Mismatched OCR", "value": { "status": "OK", "type": "MISMATCHED_OCR", "message": "OCR does not match the CIC in the INE registry", "data": { "isValid": false }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789008", "processedAt": "2026-03-15T12:35:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "cic", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'cic'" }, { "field": "citizenIdentifier", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'citizenIdentifier'" }, { "field": "ocr", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'ocr'" }, { "field": "cic", "code": "INVALID_FORMAT", "message": "CIC must be exactly 9 digits" }, { "field": "citizenIdentifier", "code": "INVALID_FORMAT", "message": "citizenIdentifier must be exactly 9 digits" }, { "field": "ocr", "code": "INVALID_FORMAT", "message": "OCR must be exactly 13 digits" } ], "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789010", "processedAt": "2026-03-15T12:35:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "INE service is currently unavailable", "data": null, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789011", "processedAt": "2026-03-15T12:35:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789012", "processedAt": "2026-03-15T12:35: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": "e97477cc-ab3d-4ad6-8325-cc58863eb3fe", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "validateVoterList", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/id/v1/voter-list-validations \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"cic\": \"123456789\", \"citizenIdentifier\": \"987654321\", \"ocr\": \"0123456789012\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/id/v1/voter-list-validations\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"cic\": \"123456789\",\n \"citizenIdentifier\": \"987654321\",\n \"ocr\": \"0123456789012\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/id/v1/voter-list-validations\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"cic\": \"123456789\",\n \"citizenIdentifier\": \"987654321\",\n \"ocr\": \"0123456789012\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"cic\\\": \\\"123456789\\\", \\\"citizenIdentifier\\\": \\\"987654321\\\", \\\"ocr\\\": \\\"0123456789012\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/id/v1/voter-list-validations\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"cic\": \"123456789\", \"citizenIdentifier\": \"987654321\", \"ocr\": \"0123456789012\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/id/v1/voter-list-validations\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"cic\\\": \\\"123456789\\\", \\\"citizenIdentifier\\\": \\\"987654321\\\", \\\"ocr\\\": \\\"0123456789012\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/id/v1/voter-list-validations\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/id/v1/voter-id-extractions": { "post": { "tags": [ "INE" ], "summary": "ID Data Extraction (OCR & Geocoding)", "description": "**Credits:** 1 per call.\n\nPerforms OCR on the front and back of a Mexican voter ID (INE / IFE) and returns the structured data printed on the credential: full name, CURP, voter key (CIC / OCR), address, photograph metadata, the document model variant (D, E, F, G, H, I — current and recent INE designs), and the MRZ read from the back when present.\n\nWhat sets this endpoint apart is **integrated address normalization + geocoding**: the address printed on the INE is rarely clean — abbreviations, missing colonia, inconsistent casing. We normalize and enrich it automatically. You get back not only the raw address text, but also:\n\n- **`addressNormalized`**: the printed INE address, normalized and enriched (corrected casing, expanded abbreviations, validated postal code, and neighborhood / municipality / state matched from the official catalog). The `geocodingStatus` field reports the match confidence: `VERIFIED` (house- or street-level match), `PARTIAL` (locality or postal-code match), or `UNVERIFIED` (no confident match).\n- **`electoralGeography`**: derived electoral district, federal entity, and polling section — useful for cross-checking with `validateVoterList`.\n- **Document model detection** (D, E, F, G, H, I) and per-model security feature validation.\n- **MRZ + QR cross-validation**: when the back contains MRZ and QR, we read both and confirm they agree with the printed fields. Mismatches are flagged.\n\nUse this endpoint to digitize voter ID capture without manual transcription, and to obtain a geo-enriched address record in a single call — eliminating a separate geocoding step in your KYC flow.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "front" ], "properties": { "front": { "type": "string", "description": "Front image in Base64 (PNG/JPG)" }, "back": { "type": "string", "description": "Back image in Base64 (PNG/JPG). Optional." } } } } } }, "responses": { "200": { "description": "Extraction results (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success D": { "summary": "Success: IFE Type D (pre-2014)", "value": { "status": "OK", "type": "SUCCESS", "message": "Document processed successfully", "data": { "documentType": "IFE", "model": "D", "personalInfo": { "givenNames": "RAQUEL", "firstSurname": "MIRANDA", "secondSurname": "ARAUJO", "dateOfBirth": "1979-02-19", "sex": "M", "gender": null, "selfIdentification": null, "curp": "MXAR790219MSLRRQ00", "electorKey": "MRARRQ79021925M800" }, "address": { "addressLine1": "C EL CAPULE 392", "addressLine2": "FRACC JARDINES DE LA SIERRA 80019", "addressLine3": "CULIACAN, SIN." }, "addressNormalized": { "geocodingStatus": "VERIFIED", "street": "Calle El Capule", "exteriorNumber": "392", "interiorNumber": null, "neighborhood": "Fraccionamiento Jardines de la Sierra", "zipCode": "80019", "municipality": "Culiacán", "state": "Sinaloa", "country": "Mexico" }, "electoralGeography": { "stateCode": "25", "stateName": "SINALOA", "municipalityCode": "006", "municipalityName": "CULIACAN", "section": "1218", "locality": "0001" }, "validity": { "registrationYear": "1999", "emissionNumber": "03", "emissionYear": "2014", "validUntilYear": "2024" }, "security": { "cic": "119195412", "ocr": "1218079288742", "citizenIdentifier": "079288742", "barCode": "119195412", "qr": "http://qr.ife.org.mx/121807928874203119195412/20140626/S/006176", "mrz": "IDMEX1191954121<<12180792887427902192M2412311MEX<03<<10110<1MIRANDAARAUJO<\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/id/v1/voter-id-extractions\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"front\": \"\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/id/v1/voter-id-extractions\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"front\": \"\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"front\\\": \\\"\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/id/v1/voter-id-extractions\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": "\"}';\n\n$ch = curl_init('https://api.origoid.com/mex/id/v1/voter-id-extractions');\ncurl_setopt_array($ch, [\n CURLOPT_POST => true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"front\": \"\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/id/v1/voter-id-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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"front\\\": \\\"\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/id/v1/voter-id-extractions\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/id/v1/qr-extractions": { "post": { "tags": [ "INE" ], "summary": "INE QR Code Data Extraction", "description": "**Credits:** 2 per call.\n\nDecrypts and parses the QR codes printed on Mexican voter IDs (INE models G, H, I and J). The two QRs on the back contain RSA-signed payloads with the holder's full record (name, CURP, voter key, address, signature). This endpoint decrypts both QRs and merges the result.\n\nUse this endpoint as a tamper-evidence check: if the QR decrypts successfully and matches the printed data, the credential is highly likely to be authentic.\n\n**Models I and J (2026+)** additionally carry a self-identified `gender` (may be `NB`), `selfIdentification` (autoadscripción, e.g. `INDÍGENA`), `ethnicGroup` (indigenous people), and the printed `address`. These are `null` on models G/H. `sex` (from the CURP) and `dateOfBirth` are present on all models.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "back" ], "properties": { "back": { "type": "string", "description": "Back image of the INE credential in Base64 (PNG/JPG). The QR code must be visible. **Required.**" } } } } } }, "responses": { "200": { "description": "Extraction results (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success G": { "summary": "Success: INE Model G", "value": { "status": "OK", "type": "SUCCESS", "message": "Document processed successfully", "data": { "documentType": "INE", "model": "G", "personalInfo": { "givenNames": "MARIA FERNANDA", "firstSurname": "LOPEZ", "secondSurname": "GODINEZ", "dateOfBirth": "1995-03-12", "sex": "M", "gender": null, "selfIdentification": null, "ethnicGroup": null, "curp": "LOGF950312MDFRPL03" }, "address": null, "electoralGeography": { "stateCode": "09", "stateName": "CIUDAD DE MÉXICO", "municipalityCode": "014", "municipalityName": "IZTAPALAPA", "section": "1832" }, "validity": { "emissionYear": "2020", "validUntilYear": "2030", "emissionDate": "2020-08-15", "emissionNumber": "1" }, "security": { "cic": "312456789", "ocr": "1832054321987", "qr": null }, "files": [ { "kind": "face", "contentType": "image/png", "sizeBytes": 20496, "content": "iVBORw0KGgoAAAANSUhEUgAAAGAAAACACAIAAAB7vvvt..." } ] }, "transactionId": "e8cbd7dc-a528-499e-b868-5fa956f30ca9", "processedAt": "2026-04-26T10:00:00-06:00", "billable": true } }, "Success H": { "summary": "Success: INE Type H (2024+, real sample, PII sanitized)", "description": "Real production payload from a Mexican INE Type H card with all personal identifiers (names, CURP, voter key) replaced with placeholders. The base64 face image is collapsed to `` for readability.", "value": { "status": "OK", "type": "SUCCESS", "message": "Document processed successfully", "data": { "documentType": "INE", "model": "H", "personalInfo": { "givenNames": "JUAN CARLOS", "firstSurname": "PEREZ", "secondSurname": "LOPEZ", "dateOfBirth": "1990-01-01", "sex": "H", "gender": null, "selfIdentification": null, "ethnicGroup": null, "curp": "PELJ900101HDFRZN02" }, "address": null, "electoralGeography": { "stateCode": "09", "stateName": "CIUDAD DE MÉXICO", "municipalityCode": null, "municipalityName": null, "section": null }, "validity": { "emissionYear": "2024", "validUntilYear": "2034", "emissionDate": "2024-02-11", "emissionNumber": "1" }, "security": { "cic": "458201673", "ocr": "4582016739210", "qr": null }, "files": [ { "kind": "face", "contentType": "image/png", "sizeBytes": 20496, "content": "" } ] }, "billable": true, "transactionId": "550e8400-e29b-41d4-a716-446655440000", "processedAt": "2026-03-15T19:23:00-06:00" } }, "Success I": { "summary": "Success: INE Type I (2026+, new generation)", "value": { "status": "OK", "type": "SUCCESS", "message": "Document processed successfully", "data": { "documentType": "INE", "model": "I", "personalInfo": { "givenNames": "DANIELA", "firstSurname": "NAVARRO", "secondSurname": "CAMPOS", "dateOfBirth": "1997-04-18", "sex": "M", "gender": "NB", "selfIdentification": "INDÍGENA", "ethnicGroup": "MAYA", "curp": "NACD970418MDFVMR05" }, "address": { "addressLine1": "AV EJERCITO NACIONAL 500", "addressLine2": "COL POLANCO 11560", "addressLine3": "MIGUEL HIDALGO, CDMX" }, "electoralGeography": { "stateCode": "09", "stateName": "CIUDAD DE MÉXICO", "municipalityCode": "016", "municipalityName": "MIGUEL HIDALGO", "section": "3844" }, "validity": { "emissionYear": "2026", "validUntilYear": "2036", "emissionDate": "2026-07-10", "emissionNumber": "02" }, "security": { "cic": "507318924", "ocr": "3844052731890", "qr": "http://qr.ine.mx/384405273189002507318924/20260710/P/038440" }, "files": [ { "kind": "face", "contentType": "image/png", "sizeBytes": 24680, "content": "iVBORw0KGgoAAAANSUhEUgAAAGAAAACACAIAAAB7vvvt..." } ] }, "transactionId": "5d2e8a41-7c93-4b6f-a802-3e1f9c6d5b70", "processedAt": "2026-07-14T18:22:05-06:00", "billable": true } }, "Unreadable": { "summary": "Error: Unreadable QR", "value": { "status": "OK", "type": "IMAGE_UNREADABLE", "message": "Image is too blurry or QR code is not clearly visible", "data": null, "transactionId": "f3a8d5d1-ff72-4584-87dd-76fd764e41b5", "processedAt": "2026-04-26T10:02:00-06:00", "billable": true } }, "Unsupported": { "summary": "Error: Unsupported Document", "value": { "status": "OK", "type": "DOCUMENT_NOT_IDENTIFIED", "message": "Document is not a supported Mexican voter ID (Models G, H, I, J only)", "data": null, "transactionId": "d3a2be72-a9f0-4b9b-9dc2-6fafa8b51723", "processedAt": "2026-04-26T10:03:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "transactionId": "e0305a4c-ebf8-478f-b2ad-632c5bd54a14", "processedAt": "2026-04-26T10:04:00-06:00", "billable": false, "errors": [ { "field": "back", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'back'" }, { "field": "back", "code": "PAYLOAD_TOO_LARGE", "message": "back exceeds 12 MB base64 length" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "Request body exceeds 28 MB" }, { "field": "back", "code": "INVALID_FORMAT", "message": "back must be a valid base64-encoded image" }, { "field": "back", "code": "UNSUPPORTED_FORMAT", "message": "Only JPEG and PNG images are supported" } ] } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "bf22e9d0-9d0c-44a0-b310-e2b47bd9d35c", "processedAt": "2026-04-26T10:05: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": "99ac06b2-4fb0-4ae7-9f95-938c84325c82", "processedAt": "2026-04-26T10:06:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "extractQrData", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/id/v1/qr-extractions \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"back\": \"\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/id/v1/qr-extractions\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"back\": \"\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/id/v1/qr-extractions\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"back\": \"\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"back\\\": \\\"\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/id/v1/qr-extractions\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": "\"}';\n\n$ch = curl_init('https://api.origoid.com/mex/id/v1/qr-extractions');\ncurl_setopt_array($ch, [\n CURLOPT_POST => true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"back\": \"\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/id/v1/qr-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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"back\\\": \\\"\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/id/v1/qr-extractions\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/global/biometrics/v1/face-matches": { "post": { "tags": [ "Biometrics" ], "summary": "Global Biometric Face Match", "description": "**Credits:** 1 per call.\n\nCompares two facial images and returns a similarity score (0–100) plus a binary match/no-match decision. Typical use is 1:1 verification between a live selfie and the photograph on an ID document.\n\nUse this endpoint to confirm that the person presenting an ID is the same person depicted on it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "face", "front" ], "properties": { "face": { "type": "string", "description": "Face image (selfie) in Base64 (PNG/JPG)" }, "front": { "type": "string", "description": "Front ID image in Base64 (PNG/JPG). Can be any official document globally." }, "threshold": { "type": "integer", "minimum": 1, "maximum": 100, "default": 90, "description": "Acceptance threshold (1-100). Default: **90** (KYC-grade). Lower (e.g. 80) is more permissive; higher is stricter. Overridable per request." }, "documentType": { "type": "string", "enum": [ "IFE", "INE", "MEX_PASSPORT", "MEX_RESIDENCE_CARD", "MEX_PROFESSIONAL_ID", "ANY" ], "description": "Optional. Use a specific type (e.g. `INE`, `MEX_PASSPORT`) for strict validation against that exact document type. Use `ANY` to require the image be some recognized ID (auto-detected) — returns `NO_DOCUMENT_DETECTED` if not. Omit it to skip document validation." } } } } } }, "responses": { "200": { "description": "Biometric analysis result (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Match INE": { "value": { "status": "OK", "type": "SUCCESS", "message": "Faces match", "data": { "faceMatchScore": 96.4, "isMatch": true, "thresholdApplied": 90, "detectedDocumentType": "INE", "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "Match Other Document": { "value": { "status": "OK", "type": "SUCCESS", "message": "Faces match", "data": { "faceMatchScore": 91.5, "isMatch": true, "thresholdApplied": 90, "detectedDocumentType": "OTHER", "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "Match With Glasses": { "value": { "status": "OK", "type": "SUCCESS", "message": "Faces match", "data": { "faceMatchScore": 92.5, "isMatch": true, "thresholdApplied": 90, "detectedDocumentType": "INE", "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": true, "wearingSunglasses": false, "faceCovered": false, "issues": [ "wearing_glasses" ] } }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "Match Face Covered": { "value": { "status": "OK", "type": "SUCCESS", "message": "Faces match", "data": { "faceMatchScore": 90.8, "isMatch": true, "thresholdApplied": 90, "detectedDocumentType": "INE", "selfieAnalysis": { "imageQuality": "good", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": true, "issues": [ "face_covered" ] } }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "Face Mismatch": { "value": { "status": "OK", "type": "FACE_MISMATCH", "message": "Faces do not match", "data": { "faceMatchScore": 41.7, "isMatch": false, "thresholdApplied": 90, "detectedDocumentType": "INE", "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "No Face In Selfie": { "value": { "status": "OK", "type": "NO_FACE_DETECTED", "message": "No face detected in the selfie image", "data": { "faceMatchScore": null, "isMatch": false, "thresholdApplied": null, "detectedDocumentType": "INE", "selfieAnalysis": null }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "No Face In Document": { "value": { "status": "OK", "type": "NO_FACE_DETECTED", "message": "No face detected in the document image", "data": { "faceMatchScore": null, "isMatch": false, "thresholdApplied": null, "detectedDocumentType": null, "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "Multiple Faces": { "value": { "status": "OK", "type": "MULTIPLE_FACES_DETECTED", "message": "Multiple faces detected in selfie", "data": { "faceMatchScore": null, "isMatch": false, "thresholdApplied": null, "detectedDocumentType": "INE", "selfieAnalysis": null }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "No Document Detected": { "value": { "status": "OK", "type": "NO_DOCUMENT_DETECTED", "message": "The provided image is not a recognized identity document", "data": { "faceMatchScore": null, "isMatch": false, "thresholdApplied": null, "detectedDocumentType": null, "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "Document Mismatch": { "value": { "status": "OK", "type": "DOCUMENT_MISMATCH", "message": "Expected MEX_PASSPORT but detected INE", "data": { "faceMatchScore": null, "isMatch": false, "thresholdApplied": null, "detectedDocumentType": "INE", "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": true } }, "Validation Error": { "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": false, "errors": [ { "field": "face", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'face'" }, { "field": "front", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'front'" }, { "field": "threshold", "code": "OUT_OF_RANGE", "message": "must be <= 100" }, { "field": "documentType", "code": "INVALID_ENUM_VALUE", "message": "must be equal to one of the allowed values" }, { "field": "face", "code": "INVALID_TYPE", "message": "must be string" }, { "field": "front", "code": "INVALID_TYPE", "message": "must be string" }, { "field": "threshold", "code": "INVALID_TYPE", "message": "must be integer" }, { "field": "threshold", "code": "OUT_OF_RANGE", "message": "must be >= 1" }, { "field": "face", "code": "INVALID_FORMAT", "message": "The 'face' parameter must be a JPG or PNG image" }, { "field": "front", "code": "INVALID_FORMAT", "message": "The 'front' parameter must be a JPG or PNG image" }, { "field": "body", "code": "MALFORMED_JSON", "message": "Malformed JSON body" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "Request body exceeds 28 MB" } ] } }, "Internal Error": { "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "5c9e1f2a-3b4c-4d5e-6f7a-8b9c0d1e2f3a", "processedAt": "2026-06-05T11:20:33.482-06:00", "billable": false } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FaceMatchData" } } } ] } } } }, "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": "ed131891-2f22-488a-84b8-fe88458f0f9d", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "matchFaces", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/global/biometrics/v1/face-matches \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"face\": \"\", \"front\": \"\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/global/biometrics/v1/face-matches\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"face\": \"\",\n \"front\": \"\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/global/biometrics/v1/face-matches\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"face\": \"\",\n \"front\": \"\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"face\\\": \\\"\\\", \\\"front\\\": \\\"\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/global/biometrics/v1/face-matches\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": "\", \"front\": \"\"}';\n\n$ch = curl_init('https://api.origoid.com/global/biometrics/v1/face-matches');\ncurl_setopt_array($ch, [\n CURLOPT_POST => true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"face\": \"\", \"front\": \"\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/global/biometrics/v1/face-matches\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"face\\\": \\\"\\\", \\\"front\\\": \\\"\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/global/biometrics/v1/face-matches\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/global/biometrics/v1/liveness-checks": { "post": { "tags": [ "Biometrics" ], "summary": "Liveness Detection", "description": "**Credits:** 1 per call.\n\nDetermines whether a selfie shows a real, live person in front of the camera (`isLive: true`) or a spoofing attempt (`isLive: false`).\n\nReturns:\n\n- **`isLive`**: the decision. `livenessScore` (0–100) is the fused output of the anti-spoofing models; the decision threshold is **62**.\n- **`confidence`**: how far the score landed from the threshold — `HIGH` (25 points or more), `MEDIUM` (10 or more) or `LOW`.\n- **`selfieAnalysis`**: quality and attribute labels of the evaluated face (image quality, orientation, eyes open, glasses, face covered, actionable `issues[]`). Same object as `matchFaces`, so both endpoints share one integration.\n\n**Multiple people in frame.** By default a selfie with another person present returns `MULTIPLE_FACES_DETECTED`. Send `allowMultipleFaces: true` to evaluate the largest face in the image instead (the person holding the phone); `selfieAnalysis` describes that same face. Only faces of at least 25% of the main face's area count as another person — people in the background do not.\n\n**Decision rule.** Accept only `type: SUCCESS` with `isLive: true`. `NO_FACE_DETECTED`, `MULTIPLE_FACES_DETECTED` and `IMAGE_UNREADABLE` also return `isLive: false`, but nothing was evaluated — `data` always carries the full object so you can read `data.isLive` without branching on `type`. Detecting a spoofing attempt is a `SUCCESS`: the service did its job.\n\n**Images.** JPG or PNG. The image is downscaled internally; no client-side resizing is needed. For best results send at least 1600 px on the longest side at JPEG quality 80 or better. The result is a liveness decision only; it does not verify identity — pair it with `matchFaces` for that.\n\n`INVALID_REQUEST` returns every problem found in `errors[]` at once (cumulative), so you can fix them in one pass.\n\n**`selfieAnalysis` reference.** Describes the evaluated face. Labels are derived from the face-analysis provider as follows:\n\n| Field | Values | Rule |\n|---|---|---|\n| `imageQuality` | `excellent` · `good` · `poor` | `excellent`: brightness ≥ 75 and sharpness ≥ 75 · `good`: both ≥ 50 · `poor`: otherwise. In practice `poor` almost always means a dark image, not an out-of-focus one. |\n| `detectionConfidence` | `high` · `medium` · `low` | `high` ≥ 95 · `medium` ≥ 80 · `low` below 80. |\n| `orientation` | `sideways` · `looking_left` · `looking_right` · `looking_up` · `looking_down` · `tilted` · `front` | Evaluated in that order, first match wins: `sideways` abs(yaw) ≥ 25° · `looking_left` yaw ≥ 10° · `looking_right` yaw ≤ −10° · `looking_up` pitch ≥ 20° · `looking_down` pitch ≤ −20° · `tilted` abs(roll) ≥ 15° · otherwise `front`. |\n| `eyesOpen`, `mouthOpen`, `wearingGlasses`, `wearingSunglasses`, `faceCovered` | `true` · `false` · `null` | `null` when the attribute could not be determined. `mouthOpen` is informational and never produces an issue. |\n\n`issues[]` lists every condition detected on the face. All possible values:\n\n| Value | Condition |\n|---|---|\n| `poor_image_quality` | `imageQuality` is `poor` |\n| `not_facing_camera` | `orientation` is not `front` |\n| `eyes_closed` | `eyesOpen` is `false` |\n| `face_covered` | `faceCovered` is `true` — mask, scarf, hand, hair over the eyes, face partly out of frame |\n| `wearing_glasses` | `wearingGlasses` is `true` — informational, not a capture problem |\n| `wearing_sunglasses` | `wearingSunglasses` is `true` |\n| `low_detection_confidence` | `detectionConfidence` is `low` |\n\nIn production about 4 in 10 legitimate selfies carry at least one issue — treat `issues[]` as retry hints, not as rejection criteria.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "selfie" ], "properties": { "selfie": { "type": "string", "description": "Selfie image of the subject in Base64 (PNG/JPG)." }, "allowMultipleFaces": { "type": "boolean", "default": false, "description": "Optional. When `false` (default), a selfie with another person in frame returns `MULTIPLE_FACES_DETECTED`. When `true`, the largest face in the image is evaluated and the others are ignored." } } } } } }, "responses": { "200": { "description": "Liveness analysis result (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success Live": { "summary": "Live person", "value": { "status": "OK", "type": "SUCCESS", "message": "Liveness check completed", "data": { "isLive": true, "livenessScore": 98, "confidence": "HIGH", "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "f2da936b-4e13-47e9-8696-8f3526cf03fd", "processedAt": "2026-09-08T12:00:00-06:00", "billable": true } }, "Success Spoofing Detected": { "summary": "Spoofing attempt detected", "value": { "status": "OK", "type": "SUCCESS", "message": "Liveness check completed", "data": { "isLive": false, "livenessScore": 0, "confidence": "HIGH", "selfieAnalysis": { "imageQuality": "good", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "abeadc90-bd61-4e9a-9914-d9bbc10d4f2f", "processedAt": "2026-09-08T12:01:00-06:00", "billable": true } }, "Success Multiple Faces Allowed": { "summary": "`allowMultipleFaces: true` — largest face evaluated", "value": { "status": "OK", "type": "SUCCESS", "message": "Liveness check completed", "data": { "isLive": true, "livenessScore": 99, "confidence": "HIGH", "selfieAnalysis": { "imageQuality": "excellent", "detectionConfidence": "high", "orientation": "front", "eyesOpen": true, "mouthOpen": false, "wearingGlasses": false, "wearingSunglasses": false, "faceCovered": false, "issues": [] } }, "transactionId": "b686ca86-6c39-4089-8553-502a4b9f6401", "processedAt": "2026-09-08T12:02:00-06:00", "billable": true } }, "No Face Detected": { "summary": "No face detected", "value": { "status": "OK", "type": "NO_FACE_DETECTED", "message": "No face detected in the image", "data": { "isLive": false, "livenessScore": null, "confidence": null, "selfieAnalysis": null }, "transactionId": "8136449e-5135-4669-9616-f27e652ea4a7", "processedAt": "2026-09-08T12:03:00-06:00", "billable": true } }, "Multiple Faces Detected": { "summary": "Another person in frame (send `allowMultipleFaces: true` to evaluate the largest face)", "value": { "status": "OK", "type": "MULTIPLE_FACES_DETECTED", "message": "Multiple faces detected in the image", "data": { "isLive": false, "livenessScore": null, "confidence": null, "selfieAnalysis": null }, "transactionId": "0a96757c-73bc-4877-bab6-80fbd3ea5a66", "processedAt": "2026-09-08T12:04:00-06:00", "billable": true } }, "Image Unreadable": { "summary": "Face too small or image unusable", "value": { "status": "OK", "type": "IMAGE_UNREADABLE", "message": "Image is too blurry or obscured to analyze", "data": { "isLive": false, "livenessScore": null, "confidence": null, "selfieAnalysis": null }, "transactionId": "79081299-a197-4192-a415-16f2365d8b6b", "processedAt": "2026-09-08T12:05:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "transactionId": "7730454b-06ed-431b-bdb5-9737986b016b", "processedAt": "2026-09-08T12:06:00-06:00", "billable": false, "errors": [ { "field": "body", "code": "INVALID_TYPE", "message": "must be object" }, { "field": "selfie", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'selfie'" }, { "field": "selfie", "code": "INVALID_TYPE", "message": "must be string" }, { "field": "allowMultipleFaces", "code": "INVALID_TYPE", "message": "must be boolean" }, { "field": "selfie", "code": "INVALID_FORMAT", "message": "The 'selfie' parameter must be a valid base64 image or accessible s3:// URI" }, { "field": "selfie", "code": "INVALID_FORMAT", "message": "The 'selfie' parameter must be a JPG or PNG image" }, { "field": "selfie", "code": "PAYLOAD_TOO_LARGE", "message": "selfie exceeds 12 MB base64 length" }, { "field": "body", "code": "MALFORMED_JSON", "message": "Malformed JSON body" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "Request body exceeds 28 MB" } ] } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "99cac343-b39b-4557-876e-08878a6d0b05", "processedAt": "2026-09-08T12:07:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The liveness verification service is currently unavailable", "data": null, "transactionId": "407d76c4-200b-4169-8668-da27d120191d", "processedAt": "2026-09-08T12:08:00-06:00", "billable": false } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LivenessData" } } } ] } } } }, "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": "2c14da6a-2358-4783-92b5-fe16d123a469", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "checkLiveness", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/global/biometrics/v1/liveness-checks \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"selfie\": \"\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/global/biometrics/v1/liveness-checks\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"selfie\": \"\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/global/biometrics/v1/liveness-checks\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"selfie\": \"\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"selfie\\\": \\\"\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/global/biometrics/v1/liveness-checks\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": "\"}';\n\n$ch = curl_init('https://api.origoid.com/global/biometrics/v1/liveness-checks');\ncurl_setopt_array($ch, [\n CURLOPT_POST => true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"selfie\": \"\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/global/biometrics/v1/liveness-checks\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"selfie\\\": \\\"\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/global/biometrics/v1/liveness-checks\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/compliance/v1/sat-69-searches": { "post": { "tags": [ "Compliance" ], "summary": "SAT Article 69 Check", "description": "**Credits:** 1 per call.\n\nValidates if an individual or legal entity is listed in the Mexican Tax Authority (SAT) Article 69 blacklist. This endpoint covers all sub-lists of Art. 69. Note: This endpoint does NOT evaluate Article 69-B (EFOS/simulated operations).\n\n**Business Rules (Search Priority):**\n1. The client must provide EITHER a name (`name` / Razón Social) OR an exact identifier (`rfc`).\n2. If `rfc` is provided, the backend performs a strict exact match. If only `name` is provided, the backend performs a highly restrictive text search.\n\n**Risk Level Matrix (`riskLevel`):**\n- `NONE`: No matches found. Safe for automated approval.\n- `LOW` (Informativo / Sin Riesgo Operativo): The subject has historical or administrative records but is legally operating. **Lists:** Condonados (Todos los decretos/artículos), Reducción Art. 74 CFF, Retorno de Inversiones, Entes Públicos y de Gobierno Omisos.\n- `MEDIUM` (Riesgo Financiero / Morosidad): The subject has active enforceable debts or the SAT declared them insolvent/uncollectible. **Lists:** Firmes, Exigibles, Cancelados (Incosteabilidad / Insolvencia).\n- `HIGH` (Riesgo Operativo Grave): The subject cannot be found by authorities or their digital billing seals (CSD) have been revoked, halting their operations. **Lists:** No Localizados, CSD Sin Efectos.\n- `CRITICAL` (Riesgo Legal / Fraude Penal): The subject has criminal convictions related to tax crimes. **Lists:** Sentencias.\n\n**Multi-match selection:** When the subject appears in more than one SAT list, the top-level `riskLevel` reflects only the record with the most recent `publicationDate`. All historical records are still returned in `matches[]` so you can audit the full timeline.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name for individuals or Legal Business Name for companies." }, "rfc": { "type": "string", "description": "Subject's RFC. Prioritized for exact matching if provided." } }, "oneOf": [ { "required": [ "name" ] }, { "required": [ "rfc" ] } ] }, "examples": { "by_name": { "summary": "By Name", "value": { "name": "JUAN PEREZ LOPEZ" } }, "by_rfc": { "summary": "By RFC", "value": { "rfc": "PELJ900101AAA" } } } } } }, "responses": { "200": { "description": "SAT Article 69 search results (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Risk: NONE": { "summary": "Risk: NONE — no SAT 69 records found", "value": { "status": "OK", "type": "SUCCESS", "message": "No SAT 69 matches found", "data": { "matchFound": false, "riskLevel": "NONE", "totalMatchesFound": 0, "matches": [] }, "transactionId": "c3d4e5f6-a7b8-9c0d-1e2f-234567890123", "processedAt": "2026-03-19T10:05:00-06:00", "billable": true } }, "Risk: LOW": { "summary": "Risk: LOW — Retorno Inversiones / Condonados", "value": { "status": "OK", "type": "SUCCESS", "message": "SAT 69 match found", "data": { "matchFound": true, "riskLevel": "LOW", "totalMatchesFound": 1, "matches": [ { "listType": "SAT_69_RETORNO_INVERSIONES", "rfc": "AAGO450423AS5", "razonSocial": "OSCAR JORGE ADAME GARZA", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_FISICA", "status": "RETORNO INVERSIONES", "taxAmount": { "amount": "226773.00", "currency": "MXN" }, "publicationDate": "2016-06-16", "state": "NUEVO LEON" } } ] }, "transactionId": "a1b2c3d4-e5f6-4789-abcd-1234567890ab", "processedAt": "2026-03-19T10:06:00-06:00", "billable": true } }, "Risk: MEDIUM": { "summary": "Risk: MEDIUM — multiple records (most recent publicationDate wins)", "value": { "status": "OK", "type": "SUCCESS", "message": "SAT 69 match found", "data": { "matchFound": true, "riskLevel": "MEDIUM", "totalMatchesFound": 2, "matches": [ { "listType": "SAT_69_FIRMES", "rfc": "AAKA5806108N2", "razonSocial": "ALFREDO ADAME VON KNOOP", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_FISICA", "status": "FIRMES", "taxAmount": null, "publicationDate": "2025-01-01", "state": "CIUDAD DE MEXICO" } }, { "listType": "SAT_69_SENTENCIAS", "rfc": "AAKA5806108N2", "razonSocial": "ALFREDO ADAME VON KNOOP", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_FISICA", "status": "SENTENCIAS", "taxAmount": null, "publicationDate": "2014-01-01", "state": "CIUDAD DE MEXICO" } } ] }, "transactionId": "f4a1ce92-2c97-4c0e-bbd6-7d80f5a9a9b1", "processedAt": "2026-03-19T10:07:00-06:00", "billable": true } }, "Risk: HIGH": { "summary": "Risk: HIGH — No Localizado", "value": { "status": "OK", "type": "SUCCESS", "message": "SAT 69 match found", "data": { "matchFound": true, "riskLevel": "HIGH", "totalMatchesFound": 1, "matches": [ { "listType": "SAT_69_NO_LOCALIZADOS", "rfc": "DMC990622AG8", "razonSocial": "2 M CONSTRUCTORA SA DE CV", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_MORAL", "status": "NO LOCALIZADOS", "taxAmount": null, "publicationDate": "2014-01-01", "state": "CIUDAD DE MEXICO" } } ] }, "transactionId": "b2c3d4e5-f6a7-8b9c-0d1e-123456789002", "processedAt": "2026-03-19T10:08:00-06:00", "billable": true } }, "Risk: CRITICAL": { "summary": "Risk: CRITICAL — Sentencias (tax-crime conviction)", "value": { "status": "OK", "type": "SUCCESS", "message": "SAT 69 match found", "data": { "matchFound": true, "riskLevel": "CRITICAL", "totalMatchesFound": 1, "matches": [ { "listType": "SAT_69_SENTENCIAS", "rfc": "AAKA5806108N2", "razonSocial": "ALFREDO ADAME VON KNOOP", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_FISICA", "status": "SENTENCIAS", "taxAmount": null, "publicationDate": "2014-01-01", "state": "CIUDAD DE MEXICO" } } ] }, "transactionId": "49ac48d4-ddf5-4408-b2a4-44fddd05ff88", "processedAt": "2026-03-19T10:09:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "body", "code": "MISSING_SEARCH_CRITERIA", "message": "You must provide either a valid identifier (rfc) or a name/razonSocial." }, { "field": "rfc", "code": "INVALID_RFC_FORMAT", "message": "The provided value does not match a valid RFC pattern" }, { "field": "name", "code": "NAME_TOO_SHORT", "message": "Name too short after removing corporate suffixes (need at least 3 chars)" }, { "field": "name", "code": "NAME_ONLY_STOPWORDS", "message": "Name contains only corporate stopwords (SA, DE, CV, etc.); add an identifying token" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "d6c4cb45-d21e-4070-a998-029968c425b8", "processedAt": "2026-03-19T10:09:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "e443e54f-4c9e-4316-9584-e4ce637b3020", "processedAt": "2026-03-19T10:10:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The SAT 69 dataset service is currently unavailable", "data": null, "transactionId": "9970628f-7808-4380-8631-0d7a0a1b3b9e", "processedAt": "2026-05-21T10:00: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": "cd8ea27f-efee-4b8c-9cfd-192946644ef3", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "searchSat69", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/compliance/v1/sat-69-searches \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"name\": \"JUAN PEREZ LOPEZ\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/compliance/v1/sat-69-searches\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"name\": \"JUAN PEREZ LOPEZ\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/compliance/v1/sat-69-searches\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"name\": \"JUAN PEREZ LOPEZ\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"name\\\": \\\"JUAN PEREZ LOPEZ\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/compliance/v1/sat-69-searches\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"name\": \"JUAN PEREZ LOPEZ\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/compliance/v1/sat-69-searches\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"name\\\": \\\"JUAN PEREZ LOPEZ\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/compliance/v1/sat-69-searches\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/compliance/v1/sat-69b-searches": { "post": { "tags": [ "Compliance" ], "summary": "SAT Article 69-B Check (EFOS)", "description": "**Credits:** 1 per call.\n\nValidates if an individual or legal entity is listed in the Mexican Tax Authority (SAT) Article 69-B blacklist. This list is specifically for EFOS (Empresas que Facturan Operaciones Simuladas), commonly known as 'Factureros' or shell companies involved in tax fraud and money laundering.\n\n**Business Rules (Search Priority):**\n1. The client must provide EITHER a name (`name` / Razón Social) OR an exact identifier (`rfc`).\n2. If `rfc` is provided, the backend performs a strict exact match. If only `name` is provided, the backend performs a highly restrictive text search.\n\n**Risk Level Matrix (`riskLevel` mapped to SAT Status):**\n- `NONE`: No matches found in the SAT 69-B list. Safe for automated approval.\n- `LOW`: The SAT status is **'Desvirtuado'** (Investigated but successfully proved innocence) or **'Sentencia Favorable'** (Won in court / cleared). Provided for audit trails and historical record.\n- `MEDIUM`: Reserved for intermediate risk states. Currently not produced by the SAT 69-B classification.\n- `HIGH`: The SAT status is **'Presunto'** (Currently under investigation for simulated operations). Extreme caution advised; usually triggers Enhanced Due Diligence (EDD) or temporal blocks.\n- `CRITICAL`: The SAT status is **'Definitivo'** (Confirmed shell company / EFOS). Legally binding block required for AML compliance.\n\n**Multi-match selection:** A taxpayer may appear in more than one record (e.g., first listed as `PRESUNTO`, later reclassified to `DEFINITIVO` or `SENTENCIA_FAVORABLE`). The top-level `riskLevel` reflects only the record with the most recent `publicationDateSat` (falling back to `publicationDateDof`). All historical records are still returned in `matches[]` so you can audit the full timeline.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name for individuals or Legal Business Name for companies." }, "rfc": { "type": "string", "description": "Subject's RFC. Prioritized for exact matching if provided." } }, "oneOf": [ { "required": [ "name" ] }, { "required": [ "rfc" ] } ] }, "examples": { "by_name": { "summary": "By Name", "value": { "name": "JUAN PEREZ LOPEZ" } }, "by_rfc": { "summary": "By RFC", "value": { "rfc": "PELJ900101AAA" } } } } } }, "responses": { "200": { "description": "SAT Article 69-B search results (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Risk: NONE": { "summary": "Risk: NONE — no SAT 69-B records found", "value": { "status": "OK", "type": "SUCCESS", "message": "No SAT 69-B matches found", "data": { "matchFound": false, "riskLevel": "NONE", "totalMatchesFound": 0, "matches": [] }, "transactionId": "c3d4e5f6-a7b8-9c0d-1e2f-234567890123", "processedAt": "2026-03-19T10:05:00-06:00", "billable": true } }, "Risk: LOW": { "summary": "Risk: LOW — Sentencia Favorable", "value": { "status": "OK", "type": "SUCCESS", "message": "SAT 69-B match found", "data": { "matchFound": true, "riskLevel": "LOW", "totalMatchesFound": 1, "matches": [ { "listType": "SAT_69B", "rfc": "XAXX010101000", "razonSocial": "EMPRESA ABSUELTA S.A. DE C.V.", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_MORAL", "status": "SENTENCIA_FAVORABLE", "publicationDateSat": "2019-02-15", "oficioSat": "500-05-2019-11223 de fecha 10 de febrero de 2019", "publicationDateDof": "2019-02-28", "oficioDof": "500-05-2019-11223 de fecha 10 de febrero de 2019" } } ] }, "transactionId": "7bc578c0-cce0-418f-9a54-24c6d95ee7f4", "processedAt": "2026-03-19T10:06:00-06:00", "billable": true } }, "Risk: HIGH": { "summary": "Risk: HIGH — Presunto (under investigation)", "value": { "status": "OK", "type": "SUCCESS", "message": "SAT 69-B match found", "data": { "matchFound": true, "riskLevel": "HIGH", "totalMatchesFound": 1, "matches": [ { "listType": "SAT_69B", "rfc": "GOMR800101XX1", "razonSocial": "GRUPO OPERATIVO MEXICANO S.A. DE C.V.", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_MORAL", "status": "PRESUNTO", "publicationDateSat": "2023-11-15", "oficioSat": "500-05-2023-14500 de fecha 10 de noviembre de 2023", "publicationDateDof": "2023-11-20", "oficioDof": "500-05-2023-14500 de fecha 10 de noviembre de 2023" } } ] }, "transactionId": "49ac48d4-ddf5-4408-b2a4-44fddd05ff88", "processedAt": "2026-03-19T10:07:00-06:00", "billable": true } }, "Risk: CRITICAL": { "summary": "Risk: CRITICAL — Definitivo (confirmed EFOS)", "value": { "status": "OK", "type": "SUCCESS", "message": "SAT 69-B match found", "data": { "matchFound": true, "riskLevel": "CRITICAL", "totalMatchesFound": 1, "matches": [ { "listType": "SAT_69B", "rfc": "ZUL131022LD6", "razonSocial": "ZULPER, S.A. DE C.V.", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_MORAL", "status": "DEFINITIVO", "publicationDateSat": "2018-09-20", "oficioSat": "500-05-2018-27059 de fecha 19 de septiembre de 2018", "publicationDateDof": "2018-10-08", "oficioDof": "500-05-2018-27059 de fecha 19 de septiembre de 2018" } } ] }, "transactionId": "b2c3d4e5-f6a7-8b9c-0d1e-123456789002", "processedAt": "2026-03-19T10:08:00-06:00", "billable": true } }, "Risk: CRITICAL (multiple records)": { "summary": "Risk: CRITICAL — multiple records (most recent publicationDateSat wins)", "value": { "status": "OK", "type": "SUCCESS", "message": "SAT 69-B match found", "data": { "matchFound": true, "riskLevel": "CRITICAL", "totalMatchesFound": 2, "matches": [ { "listType": "SAT_69B", "rfc": "AAS110331G59", "razonSocial": "ABIRA & SAFFI CORPORATIVO, S. DE R.L. DE C.V.", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_MORAL", "status": "DEFINITIVO", "publicationDateSat": "2020-06-19", "oficioSat": "500-05-2020-13691 de fecha 19 de junio de 2020", "publicationDateDof": "2020-07-07", "oficioDof": "500-05-2020-13691 de fecha 19 de junio de 2020" } }, { "listType": "SAT_69B", "rfc": "AAS110331G59", "razonSocial": "ABIRA & SAFFI CORPORATIVO, S. DE R.L. DE C.V.", "similarityScore": 100, "complianceDetails": { "taxpayerType": "PERSONA_MORAL", "status": "SENTENCIA_FAVORABLE", "publicationDateSat": "2019-12-20", "oficioSat": "500-05-2019-40235 de fecha 20 de diciembre de 2019", "publicationDateDof": "2020-01-27", "oficioDof": "500-05-2019-40235 de fecha 20 de diciembre de 2019" } } ] }, "transactionId": "6181a4a6-cbb3-4fb8-9c8a-f8eeae6c9cf6", "processedAt": "2026-03-19T10:09:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "body", "code": "MISSING_SEARCH_CRITERIA", "message": "You must provide either a valid identifier (rfc) or a name/razonSocial." }, { "field": "rfc", "code": "INVALID_RFC_FORMAT", "message": "The provided value does not match a valid RFC pattern" }, { "field": "name", "code": "NAME_TOO_SHORT", "message": "Name too short after removing corporate suffixes (need at least 3 chars)" }, { "field": "name", "code": "NAME_ONLY_STOPWORDS", "message": "Name contains only corporate stopwords (SA, DE, CV, etc.); add an identifying token" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "d6c4cb45-d21e-4070-a998-029968c425b8", "processedAt": "2026-03-19T10:09:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "70d17960-b40d-45e5-8912-3dfae1f9cc6f", "processedAt": "2026-03-19T10:10:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The SAT 69-B dataset service is currently unavailable", "data": null, "transactionId": "933cc46c-5edf-47c5-b61a-bceeac3e8185", "processedAt": "2026-05-21T10:00: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": "fafc15b2-ca42-4110-ac31-68e7a45a031e", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "searchSat69b", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/compliance/v1/sat-69b-searches \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"name\": \"JUAN PEREZ LOPEZ\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/compliance/v1/sat-69b-searches\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"name\": \"JUAN PEREZ LOPEZ\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/compliance/v1/sat-69b-searches\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"name\": \"JUAN PEREZ LOPEZ\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"name\\\": \\\"JUAN PEREZ LOPEZ\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/compliance/v1/sat-69b-searches\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"name\": \"JUAN PEREZ LOPEZ\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/compliance/v1/sat-69b-searches\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"name\\\": \\\"JUAN PEREZ LOPEZ\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/compliance/v1/sat-69b-searches\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/global/compliance/v1/ofac-searches": { "post": { "tags": [ "Compliance" ], "summary": "OFAC Sanctions List Check", "description": "**Credits:** 1 per call.\n\nSearches the consolidated OFAC sanctions lists for the provided name. Coverage includes:\n\n- **SDN consolidated** — Specially Designated Nationals (general SDN, plus sub-programs `SDGT` Specially Designated Global Terrorists and `SDNTK` Specially Designated Narcotics Traffickers / Kingpin Act).\n- **Non-SDN consolidated** — Foreign Sanctions Evaders (`FSE`), Sectoral Sanctions Identifications (`SSI`), Correspondent Account / Payable-Through Account restrictions (`CAPTA`), Menu-Based Sanctions (`NS-MBS`), Iran Sanctions Act non-SDN (`NS-ISA`), Palestinian Legislative Council (`NS-PLC`).\n- **UN consolidated sanctions** — surfaced as `OFAC_UN` for clients who want a single endpoint covering both US and UN screening.\n\nEach match carries the originating list (`listType`), the sanction programs that apply, entity type (individual, entity, vessel, aircraft), full aliases and any compliance remarks published with the record.\n\n**Risk Level Matrix (`riskLevel`):**\n- `NONE` (envelope `type: SUCCESS`): no matches at or above `minSimilarityScore`. Safe for automated approval from an OFAC perspective.\n- `CRITICAL` (envelope `type: SUCCESS`): one or more matches found in **any** OFAC or UN sanctions list. Treat as a hard block, reject the relationship, and file the SAR (Suspicious Activity Report) required by your jurisdiction.\n\nThere are intentionally only two levels. AML best practice treats any sanctions list hit — SDN, sectoral, informational, anywhere — as a binding stop. Surfacing intermediate gradations (HIGH / MEDIUM / LOW) misleads the client into believing some hits are merely advisory and is the most common cause of regulatory findings against KYC systems. The `listType` and `complianceDetails.programs` of every match are still surfaced so your compliance team can apply finer policy on top of the binary verdict.\n\n**Multi-match handling:** common names can produce dozens of fuzzy hits. The response returns **every record at or above `minSimilarityScore`**, sorted by `similarityScore` descending. There is no fixed truncation, so a genuine hit will never be hidden by a cap. If the volume of matches is higher than your review process can absorb, raise `minSimilarityScore` to tighten the match. `data.totalMatchesFound` mirrors `matches[].length` and is provided for convenience.\n\n**Which variant matched:** every entry in `matches[]` carries a `matchedOn` object indicating whether the query matched the canonical `entityName` or one of the record's aliases:\n- `matchedOn.type` is either `entityName` (the query matched the canonical name) or `alias` (the query matched an alias on the record).\n- `matchedOn.value` is the alias text that produced the hit when `type` is `alias`, and `null` when `type` is `entityName`.\n\nWhy this matters: OFAC sometimes lists a person under a family member's record (e.g. `OSEGUERA CERVANTES, Nemesio` — better known as El Mencho — is published as an alias of the canonical `OSEGUERA CERVANTES, Ruben`). Without `matchedOn` a reviewer scanning the response would see `Ruben` with score 100 and discount the hit. With `matchedOn` the alias is surfaced explicitly so the reviewer can confirm the right person was matched.\n\n**Multi-identifier matching:** `name` is required, but you can pass `passportNumber` and/or `nationalIdNumber` alongside it to tighten the match. Each extra identifier you provide is used to:\n\n- **Boost the score** when it agrees with the record (record's passport or national ID matches the one you sent → +5 added to `similarityScore`, capped at 100).\n- **Downgrade or filter the match** when it contradicts the record (different passport or national ID → −20 points). If the final score falls below `minSimilarityScore`, the record is excluded from `matches[]` entirely.\n- **Stay neutral** when the record does not publish that identifier (most OFAC records don't have a passport number, for example). Missing data never penalises a match — only contradicting data does.\n\nA `matchedOn` entry per match always carries an `identifiersMatched` array — for example `name` and `passportNumber` — listing exactly which fields agreed, so the reviewer can audit the confidence behind a hit.\n\n**Practical coverage of the identifier boost:** OFAC publishes passport numbers and national IDs on a minority of records — most often on non-Mexican subjects (Iranian, Russian, Venezuelan, Cuban records carry passports more frequently). For purely Mexican counterparties the boost rarely applies in practice: OFAC does not publish CURP, RFC appears only on a handful of records, and most Mexican subjects are sanctioned with name + aliases only. Use these identifiers for cross-border screening where the upside is real; for MX-only KYC the `name` field is what does the work and the optional identifiers stay neutral.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Full name of the individual or Legal Name of the entity. Required.", "example": "JOAQUIN GUZMAN LOERA" }, "passportNumber": { "type": "string", "description": "Passport number, normalised (trimmed, uppercase). Optional. Exact match against a record's passport ID is a strong signal — adds 5 to the score and is reported in `matchedOn.identifiersMatched`. A mismatch drops the score by 20.", "example": "G01234567" }, "nationalIdNumber": { "type": "string", "description": "National identifier as published by OFAC — typically `National ID`, `Cedula`, `RFC`, `SSN`, or `Tax ID` depending on jurisdiction. Optional. Normalised (trimmed, uppercase). Exact match adds 5 to the score; mismatch drops 20. OFAC does not publish CURP, and RFC appears only on a handful of records, so for Mexican subjects this field is usually neutral. Highest practical value is for cross-border screening of foreign counterparties.", "example": "BC166787" }, "minSimilarityScore": { "type": "integer", "maximum": 100, "default": 90, "description": "Minimum similarity score required to return a fuzzy match. Defaults to 90 — a conservative threshold tuned to suppress common-name false positives. Lower it for broader recall when manual review is in place; raise it for stricter automated approval. There is no enforced floor — you can request very low thresholds, but the lower you go the noisier the response will be. The final score after multi-identifier boosts and penalties is the value compared against this threshold." } } }, "examples": { "Name only (basic)": { "summary": "Name only (basic)", "value": { "name": "JOAQUIN GUZMAN LOERA" } }, "Name + passport (cross-border KYC)": { "summary": "Name + passport (cross-border KYC)", "value": { "name": "Abu Sufian al-Salamabi Muhammed Ahmed Abd al-Razziq", "passportNumber": "BC166787" } }, "Name + national ID (cross-border KYC)": { "summary": "Name + national ID (cross-border KYC)", "value": { "name": "JOAQUIN GUZMAN LOERA", "nationalIdNumber": "BC166787" } } } } } }, "responses": { "200": { "description": "OFAC search results (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Risk: NONE": { "summary": "Risk: NONE — no OFAC or UN sanctions match", "value": { "status": "OK", "type": "SUCCESS", "message": "No OFAC matches found", "data": { "matchFound": false, "riskLevel": "NONE", "totalMatchesFound": 0, "matches": [] }, "transactionId": "9041aa05-782b-461e-9033-5e07b2ad55fc", "processedAt": "2026-03-19T10:00:00-06:00", "billable": true } }, "Risk: CRITICAL": { "summary": "Risk: CRITICAL — alias match (\"EL CHAPO\") against canonical SDN record", "value": { "status": "OK", "type": "SUCCESS", "message": "OFAC match found", "data": { "matchFound": true, "riskLevel": "CRITICAL", "totalMatchesFound": 1, "matches": [ { "listType": "OFAC_SDNTK", "entityName": "GUZMAN LOERA, Joaquin Archivaldo", "recordType": "INDIVIDUAL", "similarityScore": 100, "registeredAddress": "Mexico", "matchedOn": { "type": "alias", "value": "GUZMAN, Chapo", "identifiersMatched": [ "name" ] }, "complianceDetails": { "programs": [ "SDNTK" ], "aliases": [ "EL CHAPO", "EL RAPIDO", "SHORTY" ], "nationality": "MEX", "dateOfBirth": "1954-12-25", "remarks": "Confirmed senior leader of the Sinaloa Cartel." } } ] }, "transactionId": "3d272616-b391-4930-9391-dc4557e77e01", "processedAt": "2026-03-19T10:01:00-06:00", "billable": true } }, "Risk: CRITICAL (high-confidence multi-identifier)": { "summary": "Risk: CRITICAL — name + passportNumber both match (boost applied)", "value": { "status": "OK", "type": "SUCCESS", "message": "OFAC match found", "data": { "matchFound": true, "riskLevel": "CRITICAL", "totalMatchesFound": 1, "matches": [ { "listType": "OFAC_SDGT", "entityName": "'ABD AL-RAZZIQ, Abu Sufian al-Salamabi Muhammed Ahmed", "recordType": "INDIVIDUAL", "similarityScore": 100, "registeredAddress": "Khartoum, Sudan", "matchedOn": { "type": "entityName", "value": null, "identifiersMatched": [ "name", "passportNumber" ] }, "complianceDetails": { "programs": [ "SDGT" ], "aliases": [ "ABU SUFIAN ABD AL-RAZZIQ" ], "nationality": "SDN", "dateOfBirth": "1972-01-01", "remarks": "Passport No. BC166787 (Sudan)." } } ] }, "transactionId": "67a9fe23-1c15-4d8d-b30e-2c1aef84c031", "processedAt": "2026-03-19T10:01:30-06:00", "billable": true } }, "Risk: CRITICAL (multiple records)": { "summary": "Risk: CRITICAL — common name, all 28 matches returned (no cap)", "value": { "status": "OK", "type": "SUCCESS", "message": "OFAC match found", "data": { "matchFound": true, "riskLevel": "CRITICAL", "totalMatchesFound": 28, "matches": [ { "listType": "OFAC_SDN", "entityName": "MEDINA HERNANDEZ, Jose", "recordType": "INDIVIDUAL", "similarityScore": 100, "registeredAddress": "Sinaloa, Mexico", "matchedOn": { "type": "entityName", "value": null, "identifiersMatched": [ "name" ] }, "complianceDetails": { "programs": [ "SDNTK" ], "aliases": [ "EL JEFE" ], "nationality": "MEX", "dateOfBirth": "1972-06-14", "remarks": "DOJ-indicted trafficker, multiple seizures linked to Pacific corridor." } }, { "listType": "OFAC_SSI", "entityName": "MEDINA, Jose Manuel", "recordType": "INDIVIDUAL", "similarityScore": 96, "registeredAddress": "Moscow, Russian Federation", "matchedOn": { "type": "entityName", "value": null, "identifiersMatched": [ "name" ] }, "complianceDetails": { "programs": [ "UKRAINE-EO13662" ], "aliases": [], "nationality": "RUS", "dateOfBirth": null, "remarks": "Listed as sectoral; restrictions on equity / new debt transactions per Directive 1." } }, { "listType": "OFAC_UN", "entityName": "JOSE MEDINA RAMIREZ", "recordType": "INDIVIDUAL", "similarityScore": 93, "registeredAddress": "Caracas, Venezuela", "matchedOn": { "type": "alias", "value": "JOSE A. MEDINA", "identifiersMatched": [ "name" ] }, "complianceDetails": { "programs": [ "UN-1267" ], "aliases": [ "JOSE A. MEDINA" ], "nationality": "VEN", "dateOfBirth": "1968-03-02", "remarks": "UN consolidated list, ISIL/Da'esh and Al-Qaida sanctions list." } } ] }, "transactionId": "f9b1cad3-5a98-4d62-bef0-c9d0e5b7c1aa", "processedAt": "2026-03-19T10:02:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "name", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'name'" }, { "field": "name", "code": "NAME_TOO_SHORT", "message": "name must be at least 2 characters" }, { "field": "name", "code": "NAME_ONLY_STOPWORDS", "message": "name cannot consist solely of stopwords" }, { "field": "minSimilarityScore", "code": "OUT_OF_RANGE", "message": "minSimilarityScore must be 100 or below" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "fdfdaa1f-d61d-4910-b161-87c976fc85d0", "processedAt": "2026-03-19T10:06:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "b0d241cb-f224-425a-9fe3-4be793e2d541", "processedAt": "2026-03-19T10:07:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The OFAC sanctions list service is currently unavailable. Please retry.", "data": null, "transactionId": "8718e5d5-0691-4b2a-9bab-2baa1d539c5e", "processedAt": "2026-05-21T10:00: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": "d018fa81-8e77-4e51-894b-168be3667421", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "searchOfac", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/global/compliance/v1/ofac-searches \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"Abu Sufian al-Salamabi Muhammed Ahmed Abd al-Razziq\",\n \"passportNumber\": \"BC166787\"\n }'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/global/compliance/v1/ofac-searches\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"name\": \"Abu Sufian al-Salamabi Muhammed Ahmed Abd al-Razziq\",\n \"passportNumber\": \"BC166787\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/global/compliance/v1/ofac-searches\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"name\": \"Abu Sufian al-Salamabi Muhammed Ahmed Abd al-Razziq\",\n \"passportNumber\": \"BC166787\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"name\\\": \\\"Abu Sufian al-Salamabi Muhammed Ahmed Abd al-Razziq\\\", \\\"passportNumber\\\": \\\"BC166787\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/global/compliance/v1/ofac-searches\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"name\": \"Abu Sufian al-Salamabi Muhammed Ahmed Abd al-Razziq\", \"passportNumber\": \"BC166787\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/global/compliance/v1/ofac-searches\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"name\\\": \\\"Abu Sufian al-Salamabi Muhammed Ahmed Abd al-Razziq\\\", \\\"passportNumber\\\": \\\"BC166787\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/global/compliance/v1/ofac-searches\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/compliance/v1/peps-searches": { "post": { "tags": [ "Compliance" ], "summary": "PEP (Politically Exposed Person) Check", "description": "**Credits:** 2 per call.\n\nSearches the consolidated PEP (Politically Exposed Persons) database for a subject — covering active PEPs, former PEPs (`EX_PEP`), and their immediate family and close associates (`PEP_AFFINITY`, `EX_PEP_AFFINITY`).\n\n**Input flexibility — three valid invocation forms:**\n\nThe endpoint accepts a search in any of three forms — pick the one that matches the data you have on hand. You may include `nationalIdNumber` alongside any of them to tighten the match.\n\n1. **Single name (`name`)** — pass the full name as one string. Quick and convenient when you only have the full name as a single value.\n2. **Separated name (`givenNames` + `firstSurname` + optional `secondSurname`)** — Mexican-style split. **Strongly recommended for best match quality**, because the matching engine can apply per-component logic that produces fewer false positives on compound first names and compound surnames. When using this form, both `givenNames` and `firstSurname` are required.\n3. **Identifier only (`nationalIdNumber`)** — pass a CURP or RFC by itself when that is all you have. The search runs against records that publish the identifier.\n\nIf more than one form is sent (for example `name` plus separated fields), the separated fields take precedence over `name`. The `nationalIdNumber` is normalised (trim, uppercase) and reported back per match in `matchedOn.identifiersMatched` and in the standalone `identifierMatch` field.\n\n**Risk Level Matrix (`riskLevel`):**\n\nEach match in `matches[]` has a base severity per its `listType`:\n\n| `listType` | base severity |\n|---|---|\n| `PEP_ACTIVE` | HIGH |\n| `EX_PEP` | MEDIUM |\n| `PEP_INACTIVE` | MEDIUM |\n| `PEP_AFFINITY` | MEDIUM |\n| `EX_PEP_AFFINITY` | LOW |\n\nThe endpoint `riskLevel` is the **maximum** severity across `matches[]`:\n\n- `NONE` — no matches at or above `minSimilarityScore`. Safe for automated approval from a PEP perspective.\n- `LOW` — only `EX_PEP_AFFINITY` hits found (family or close associate of a former PEP).\n- `MEDIUM` — at least one `EX_PEP`, `PEP_INACTIVE`, or `PEP_AFFINITY` hit.\n- `HIGH` — at least one `PEP_ACTIVE` hit. Aligned with the categories that FATF Recommendation 12 and Mexican LFPIORPI flag for Enhanced Due Diligence (EDD).\n\n`riskLevel` is a screening signal intended to feed your compliance workflow. Combine it with `identifierMatch`, `similarityScore`, and the per-match `complianceDetails` we surface so your team can apply its own internal policy.\n\n**Which variant matched:** every entry in `matches[]` carries a `matchedOn` object identifying the canonical record that was hit and an `identifiersMatched` array — for example `name` and `nationalIdNumber` — listing which fields agreed. The standalone `identifierMatch` field exposes the precision of the identifier comparison (`EXACT`, `PARTIAL`, `MISMATCH`, or `NOT_PROVIDED` when no identifier was sent). Use these together to audit the confidence behind a hit.\n\n**How `similarityScore` is computed:** the score reflects **combined name + identifier confidence**, not name alone. A match's `similarityScore` is the higher of (a) the name match quality and (b) the strength of the identifier comparison — an `EXACT` `nationalIdNumber` match contributes a full-confidence score, a `PARTIAL` match contributes a strong-but-not-certain score, and `MISMATCH` / `NOT_PROVIDED` contribute nothing (the name drives the score in those cases). This means a search by `nationalIdNumber` alone still returns a high-confidence hit even though no name was supplied to compare — a CURP or RFC coincidence is a deterministic identity signal. Inspect `identifierMatch` and `matchedOn.identifiersMatched` to see *why* a given match scored the way it did.\n\n**Multi-match handling:** the response returns every match at or above `minSimilarityScore`, sorted by `similarityScore` descending. `data.totalMatchesFound` mirrors `matches[].length` and is provided for convenience.\n\nUse this endpoint as part of AML programs where screening counterparties against PEPs is part of your KYC workflow — common in regulated financial services, cross-border payments, and onboarding pipelines.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the subject (single string). Optional alternative to the split `givenNames` / `firstSurname` format. Use this when you only have the full name as one value (form input, OCR extraction). For best match quality, prefer the separated fields below.", "example": "ANDRES MANUEL LOPEZ OBRADOR" }, "givenNames": { "type": "string", "description": "Subject's given name(s). Use together with `firstSurname` for the most precise matching. Recommended over the single `name` field whenever the components are available.", "example": "ANDRES MANUEL" }, "firstSurname": { "type": "string", "description": "Subject's first (paternal) surname. Use with `givenNames` for best match quality.", "example": "LOPEZ" }, "secondSurname": { "type": "string", "description": "Subject's second (maternal) surname. Optional.", "example": "OBRADOR" }, "nationalIdNumber": { "type": "string", "description": "National identifier — CURP (18 chars) or RFC (12-13 chars). Optional. Normalised (trimmed, uppercase). When provided, it is reported back per match in `matchedOn.identifiersMatched` and in the standalone `identifierMatch` field so the reviewer can audit the precision of the hit. Examples: `LOOA531113HTCPBN07` (CURP), `LOOA531113FI5` (RFC).", "example": "LOOA531113HTCPBN07" }, "minSimilarityScore": { "type": "integer", "maximum": 100, "default": 70, "description": "Minimum similarity score required to return a match. Defaults to 70 — a balanced threshold for PEP screening. Lower it for broader recall when manual review is in place; raise it for stricter automated approval. There is no enforced floor — you can request very low thresholds, but the lower you go the noisier the response will be. The threshold is compared against the combined name + identifier `similarityScore` (see the description), so a search by `nationalIdNumber` alone with an exact match is not filtered out even though no name was provided to compare." } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "givenNames", "firstSurname" ] }, { "required": [ "nationalIdNumber" ] } ] }, "examples": { "By single name (basic)": { "summary": "By single name (basic)", "value": { "name": "ANDRES MANUEL LOPEZ OBRADOR" } }, "By separated name (recommended)": { "summary": "By separated name (recommended for best match)", "value": { "givenNames": "ANDRES MANUEL", "firstSurname": "LOPEZ", "secondSurname": "OBRADOR" } }, "By separated name + CURP": { "summary": "By separated name + CURP (highest confidence)", "value": { "givenNames": "ANDRES MANUEL", "firstSurname": "LOPEZ", "secondSurname": "OBRADOR", "nationalIdNumber": "LOOA531113HTCPBN07" } }, "By single name + RFC": { "summary": "By single name + RFC", "value": { "name": "ANDRES MANUEL LOPEZ OBRADOR", "nationalIdNumber": "LOOA531113FI5" } }, "By identifier only (CURP)": { "summary": "By identifier only (CURP)", "value": { "nationalIdNumber": "LOOA531113HTCPBN07" } } } } } }, "responses": { "200": { "description": "PEP search results (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Risk: NONE": { "summary": "Risk: NONE — no PEP match", "value": { "status": "OK", "type": "SUCCESS", "message": "No PEPs matches found", "data": { "matchFound": false, "riskLevel": "NONE", "totalMatchesFound": 0, "matches": [] }, "transactionId": "d2b0b572-0be8-4744-bf0d-72f21135125b", "processedAt": "2026-03-19T10:05:00-06:00", "billable": true } }, "Risk: LOW": { "summary": "Risk: LOW — only EX_PEP_AFFINITY hit", "value": { "status": "OK", "type": "SUCCESS", "message": "PEPs match found", "data": { "matchFound": true, "riskLevel": "LOW", "totalMatchesFound": 1, "matches": [ { "listType": "EX_PEP_AFFINITY", "entityName": "ROSA MARIA HERNANDEZ MARTINEZ", "recordType": "INDIVIDUAL", "similarityScore": 78, "identifierMatch": "NOT_PROVIDED", "matchedOn": { "type": "entityName", "value": null, "identifiersMatched": [ "name" ] }, "complianceDetails": { "position": null, "institution": null, "status": "UNKNOWN", "positionEndDate": null, "dateOfBirth": null, "curp": null, "rfc": null, "registeredAddress": "MEXICO" } } ] }, "transactionId": "e9af2c47-1b94-4a23-a0a6-5fa6d3eed101", "processedAt": "2026-03-19T10:00:00-06:00", "billable": true } }, "Risk: MEDIUM": { "summary": "Risk: MEDIUM — EX_PEP hit (former office-holder)", "value": { "status": "OK", "type": "SUCCESS", "message": "PEPs match found", "data": { "matchFound": true, "riskLevel": "MEDIUM", "totalMatchesFound": 2, "matches": [ { "listType": "EX_PEP", "entityName": "LOPEZ OBRADOR ANDRES MANUEL", "recordType": "INDIVIDUAL", "similarityScore": 100, "identifierMatch": "EXACT", "matchedOn": { "type": "entityName", "value": null, "identifiersMatched": [ "name", "nationalIdNumber" ] }, "complianceDetails": { "position": "PRESIDENTE DE LOS ESTADOS UNIDOS MEXICANOS", "institution": "Gobierno de los Estados Unidos Mexicanos", "status": "INACTIVE", "positionEndDate": "2024-09", "dateOfBirth": "1953-11-13", "curp": "LOOA531113HTCPBN07", "rfc": "LOOA531113FI5", "registeredAddress": "C ODONTOLOGIA 57 EDIF B, DEPT 301, COYOACAN, MEXICO" } }, { "listType": "PEP_AFFINITY", "entityName": "PIO LORENZO LOPEZ OBRADOR", "recordType": "INDIVIDUAL", "similarityScore": 80, "identifierMatch": "NOT_PROVIDED", "matchedOn": { "type": "entityName", "value": null, "identifiersMatched": [ "name" ] }, "complianceDetails": { "position": null, "institution": null, "status": "UNKNOWN", "positionEndDate": null, "dateOfBirth": null, "curp": null, "rfc": null, "registeredAddress": "MEXICO" } } ] }, "transactionId": "b1c2d3e4-f5a6-7b8c-9d0e-123456789001", "processedAt": "2026-03-19T10:01:00-06:00", "billable": true } }, "Risk: HIGH": { "summary": "Risk: HIGH — sitting PEP, EDD required", "value": { "status": "OK", "type": "SUCCESS", "message": "PEPs match found", "data": { "matchFound": true, "riskLevel": "HIGH", "totalMatchesFound": 1, "matches": [ { "listType": "PEP_ACTIVE", "entityName": "SHEINBAUM PARDO CLAUDIA", "recordType": "INDIVIDUAL", "similarityScore": 100, "identifierMatch": "EXACT", "matchedOn": { "type": "entityName", "value": null, "identifiersMatched": [ "name", "nationalIdNumber" ] }, "complianceDetails": { "position": "PRESIDENTA DE LOS ESTADOS UNIDOS MEXICANOS", "institution": "Gobierno de los Estados Unidos Mexicanos", "status": "ACTIVE", "positionEndDate": null, "dateOfBirth": "1962-06-24", "curp": "SEPC620624MDFHRL05", "rfc": "SEPC620624C57", "registeredAddress": "CIUDAD DE MEXICO, MEXICO" } } ] }, "transactionId": "c2d3e4f5-a6b7-8c9d-0e12-3456789ab012", "processedAt": "2026-03-19T10:02:00-06:00", "billable": true } }, "Risk: MEDIUM (identifier-only search)": { "summary": "Risk: MEDIUM — searched by CURP alone, exact identifier match", "value": { "status": "OK", "type": "SUCCESS", "message": "PEPs match found", "data": { "matchFound": true, "riskLevel": "MEDIUM", "totalMatchesFound": 1, "matches": [ { "listType": "EX_PEP", "entityName": "LOPEZ OBRADOR ANDRES MANUEL", "recordType": "INDIVIDUAL", "similarityScore": 100, "identifierMatch": "EXACT", "matchedOn": { "type": "entityName", "value": null, "identifiersMatched": [ "nationalIdNumber" ] }, "complianceDetails": { "position": "PRESIDENTE DE LOS ESTADOS UNIDOS MEXICANOS", "institution": "Gobierno de los Estados Unidos Mexicanos", "status": "INACTIVE", "positionEndDate": "2024-09", "dateOfBirth": "1953-11-13", "curp": "LOOA531113HTCPBN07", "rfc": "LOOA531113FI5", "registeredAddress": "C ODONTOLOGIA 57 EDIF B, DEPT 301, COYOACAN, MEXICO" } } ] }, "transactionId": "f3e4d5c6-b7a8-9c0d-1e23-456789abc123", "processedAt": "2026-03-19T10:03:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "body", "code": "MISSING_REQUIRED_FIELD", "message": "Provide one of: `name` (single string), or both `givenNames` and `firstSurname` (separated form), or `nationalIdNumber` (CURP/RFC)." }, { "field": "nationalIdNumber", "code": "INVALID_FORMAT", "message": "nationalIdNumber must match CURP (18 characters) or RFC (12-13 characters) format" }, { "field": "firstSurname", "code": "NAME_TOO_SHORT", "message": "firstSurname must be at least 2 characters" }, { "field": "name", "code": "NAME_ONLY_STOPWORDS", "message": "name cannot consist solely of stopwords" }, { "field": "minSimilarityScore", "code": "OUT_OF_RANGE", "message": "minSimilarityScore must be 100 or below" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "22cbcaa5-ba6c-45cc-a1b0-f9c048e4f481", "processedAt": "2026-03-19T10:06:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "716080c8-5ec0-48a7-892d-fb88f1ad55a0", "processedAt": "2026-03-19T10:07:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The PEP database service is currently unavailable", "data": null, "transactionId": "878bb9a5-16ee-405e-88ed-8de43ba99401", "processedAt": "2026-05-21T10:00: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": "fb9c33a5-ee2f-42b2-8467-ff6807e14beb", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "searchPeps", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/compliance/v1/peps-searches \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"givenNames\": \"ANDRES MANUEL\", \"firstSurname\": \"LOPEZ\", \"secondSurname\": \"OBRADOR\", \"nationalIdNumber\": \"LOOA531113HTCPBN07\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/compliance/v1/peps-searches\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"givenNames\": \"ANDRES MANUEL\",\n \"firstSurname\": \"LOPEZ\",\n \"secondSurname\": \"OBRADOR\",\n \"nationalIdNumber\": \"LOOA531113HTCPBN07\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/compliance/v1/peps-searches\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"givenNames\": \"ANDRES MANUEL\",\n \"firstSurname\": \"LOPEZ\",\n \"secondSurname\": \"OBRADOR\",\n \"nationalIdNumber\": \"LOOA531113HTCPBN07\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"givenNames\\\": \\\"ANDRES MANUEL\\\", \\\"firstSurname\\\": \\\"LOPEZ\\\", \\\"secondSurname\\\": \\\"OBRADOR\\\", \\\"nationalIdNumber\\\": \\\"LOOA531113HTCPBN07\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/compliance/v1/peps-searches\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"givenNames\": \"ANDRES MANUEL\", \"firstSurname\": \"LOPEZ\", \"secondSurname\": \"OBRADOR\", \"nationalIdNumber\": \"LOOA531113HTCPBN07\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/compliance/v1/peps-searches\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"givenNames\\\": \\\"ANDRES MANUEL\\\", \\\"firstSurname\\\": \\\"LOPEZ\\\", \\\"secondSurname\\\": \\\"OBRADOR\\\", \\\"nationalIdNumber\\\": \\\"LOOA531113HTCPBN07\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/compliance/v1/peps-searches\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/global/email/v1/email-validations": { "post": { "tags": [ "Email" ], "summary": "Email Deliverability & Fraud Validation", "description": "**Credits:** 1 per call.\n\nValidates an email address for deliverability and risk. Returns the normalized address, deliverability verdict (`deliverable`, `risky`, `undeliverable`), a quality score (0–100), a toxicity score, and a set of boolean verdicts (`isFree`, `isDisposable`, `isRoleAccount`, `isFull`, `isCatchAll`, `isToxic`).\n\nUse this endpoint at signup time to reject typos and disposable addresses before they enter your database, reducing bounce rates on transactional email and fraud signals from throwaway accounts.\n\n**`riskLevel` reference** — standardized scoring you can branch on:\n\n| Level | When |\n|---|---|\n| `NONE` | Mailbox is deliverable and not flagged as disposable or toxic. |\n| `MEDIUM` | Domain is catch-all — accepts every address, so the specific mailbox cannot be confirmed to exist. |\n| `HIGH` | Deliverability is `risky` or `unknown` (e.g. mail server rejects probes), OR the domain belongs to a disposable / temporary email provider (Mailinator, 10minutemail, Guerrillamail, etc.). |\n| `CRITICAL` | Mailbox is `undeliverable` (does not exist or is full), OR the address scores above 40 on the toxicity index (associated with spam / abuse). |\n\nThe `verdicts` object always carries the underlying signals (`isFree`, `isDisposable`, `isRoleAccount`, `isFull`, `isCatchAll`, `isToxic`) so you can apply your own scoring on top if you need finer granularity.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "example": "user@example.com", "description": "The email address to be validated." } } } } } }, "responses": { "200": { "description": "Validation results (Strict Envelope Pattern).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "Risk: NONE": { "summary": "Risk: NONE — deliverable mailbox", "value": { "status": "OK", "type": "SUCCESS", "message": "Email is valid and active", "data": { "email": "user@example.com", "deliverability": "deliverable", "riskLevel": "NONE", "score": 100, "toxicityScore": 0, "verdicts": { "isFree": false, "isDisposable": false, "isRoleAccount": false, "isFull": false, "isCatchAll": false, "isToxic": false }, "infrastructure": { "domain": "origoid.com", "provider": "amazon.com", "mxRecord": "inbound-smtp.mx-central-2.amazonaws.com." } }, "transactionId": "550e8400-e29b-41d4-a716-446655440000", "processedAt": "2026-03-07T14:23:00-06:00", "billable": true } }, "Risk: MEDIUM": { "summary": "Risk: MEDIUM — catch-all domain (mailbox cannot be confirmed)", "value": { "status": "OK", "type": "SUCCESS", "message": "Mailbox cannot be confirmed", "data": { "email": "contacto@empresa.com", "deliverability": "risky", "riskLevel": "MEDIUM", "score": 75, "toxicityScore": 10, "verdicts": { "isFree": false, "isDisposable": false, "isRoleAccount": true, "isFull": false, "isCatchAll": true, "isToxic": false }, "infrastructure": { "domain": "empresa.com", "provider": "microsoft.com", "mxRecord": "mx-pro.outlook.com" } }, "transactionId": "660e8400-e29b-41d4-a716-446655441111", "processedAt": "2026-03-07T14:24:00-06:00", "billable": true } }, "Risk: HIGH": { "summary": "Risk: HIGH — disposable email domain detected", "value": { "status": "OK", "type": "SUCCESS", "message": "Disposable email domain detected", "data": { "email": "user123@mailinator.com", "deliverability": "deliverable", "riskLevel": "HIGH", "score": 60, "toxicityScore": 0, "verdicts": { "isFree": false, "isDisposable": true, "isRoleAccount": false, "isFull": false, "isCatchAll": true, "isToxic": false }, "infrastructure": { "domain": "mailinator.com", "provider": "mailinator.com", "mxRecord": "mail2.mailinator.com" } }, "transactionId": "880e8400-e29b-41d4-a716-446655443333", "processedAt": "2026-03-07T14:25:00-06:00", "billable": true } }, "Risk: CRITICAL": { "summary": "Risk: CRITICAL — mailbox does not exist", "value": { "status": "OK", "type": "SUCCESS", "message": "The email account does not exist", "data": { "email": "test@falso.com", "deliverability": "undeliverable", "riskLevel": "CRITICAL", "score": 0, "toxicityScore": 0, "verdicts": { "isFree": false, "isDisposable": false, "isRoleAccount": false, "isFull": false, "isCatchAll": false, "isToxic": false }, "infrastructure": { "domain": "falso.com", "provider": "unknown", "mxRecord": null } }, "transactionId": "770e8400-e29b-41d4-a716-446655442222", "processedAt": "2026-03-07T14:26:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "email", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'email'" }, { "field": "email", "code": "INVALID_FORMAT", "message": "email must be a valid email address" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "990e8400-e29b-41d4-a716-446655444444", "processedAt": "2026-03-07T14:27:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "a1b2c3d4-e5f6-7a8b-9c0d-123456789012", "processedAt": "2026-03-07T14:28:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "Email validation service is currently unavailable. Please retry.", "data": null, "transactionId": "3b992ac1-21df-4235-bfce-70bd3d1c8e6f", "processedAt": "2026-05-21T10:00:00-06:00", "billable": false } } } } } }, "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": "18967012-c346-4f94-8668-3b4372694894", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "validateEmail", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/global/email/v1/email-validations \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"email\": \"user@example.com\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/global/email/v1/email-validations\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"email\": \"user@example.com\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/global/email/v1/email-validations\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"email\": \"user@example.com\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"email\\\": \\\"user@example.com\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/global/email/v1/email-validations\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"email\": \"user@example.com\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/global/email/v1/email-validations\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"email\\\": \\\"user@example.com\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/global/email/v1/email-validations\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/documents/v1/proof-of-address-extractions": { "post": { "tags": [ "Proof of Address" ], "summary": "Universal Extraction (Proof of Address)", "description": "**Credits:** 1 per call.\n\nPerforms 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.\n\nReturns:\n\n- **`provider`**: the issuing utility or institution (CFE, Telmex, Agua, etc.), so you can apply provider-specific business rules and recognize legitimate document layouts.\n- **`personalInfo`**: holder name as printed on the document.\n- **`address`**: full address as printed (street, exterior / interior number, neighborhood, municipality, state, postal code).\n- **`billing`**: issuance date, account number, period covered.\n- **`validations`**: flags about document age, document type detection confidence, and structural consistency checks.\n\nUse this endpoint to automate address verification in KYC flows. The extracted address can be cross-checked against the address your customer submitted at signup.", "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" } } } } }, "operationId": "extractProofOfAddress", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/documents/v1/proof-of-address-extractions \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"file\": \"\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/documents/v1/proof-of-address-extractions\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"file\": \"\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/documents/v1/proof-of-address-extractions\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"file\": \"\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"file\\\": \\\"\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/documents/v1/proof-of-address-extractions\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": "\"}';\n\n$ch = curl_init('https://api.origoid.com/mex/documents/v1/proof-of-address-extractions');\ncurl_setopt_array($ch, [\n CURLOPT_POST => true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"file\\\": \\\"\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/documents/v1/proof-of-address-extractions\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/fiscal/v1/rfc-validations": { "post": { "tags": [ "Fiscal" ], "summary": "RFC Status and LCO Validation", "description": "**Credits:** 1 per call.\n\nValidates the structure and current status of a Mexican RFC (Registro Federal de Contribuyentes) against the SAT registry. Returns the taxpayer type (individual or legal entity), registration status, and the official SAT message.\n\nUse this endpoint to confirm that the RFC your customer provided is real, well-formed, and currently active with SAT before extending credit, issuing invoices, or signing contracts.\n\n**Risk Level Matrix (`riskLevel`):**\n- `NONE` (envelope `type: SUCCESS`): RFC exists in the SAT padrón and is authorized to issue / receive invoices (`isBillable: true`). Safe for automated approval.\n- `LOW` (envelope `type: RFC_NOT_INVOICEABLE`): RFC exists in the SAT padrón but is **restricted** for invoicing — typically a legal entity that has not completed its fiscal-status onboarding or has been suspended. The taxpayer is real, just not currently invoiceable.\n- `CRITICAL` (envelope `type: RFC_NOT_FOUND`): RFC is **not registered** in the SAT padrón. Either it was never issued, or the value provided is a typo or fabricated. Do not extend credit, issue invoices, or accept as a counterparty without further verification.\n\n`MEDIUM` and `HIGH` are not produced by this endpoint — the SAT padrón only distinguishes the three outcomes above.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rfc" ], "properties": { "rfc": { "type": "string", "description": "Taxpayer's RFC (12 or 13 characters).", "example": "GARM900101HDF" } } } } } }, "responses": { "200": { "description": "RFC Validation Result (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Risk: NONE": { "summary": "Risk: NONE — RFC valid & invoiceable", "value": { "status": "OK", "type": "SUCCESS", "message": "RFC is valid and authorized for invoicing", "data": { "rfc": "GARM900101HDF", "isValid": true, "isBillable": true, "taxpayerType": "PERSONA_FISICA", "riskLevel": "NONE", "officialMessage": "RFC válido, y susceptible de recibir facturas" }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789001", "processedAt": "2026-03-19T10:00:00-06:00", "billable": true } }, "Risk: LOW": { "summary": "Risk: LOW — RFC valid but restricted for invoicing", "value": { "status": "OK", "type": "RFC_NOT_INVOICEABLE", "message": "RFC exists but is restricted for invoicing", "data": { "rfc": "TAVM150612XYZ", "isValid": true, "isBillable": false, "taxpayerType": "PERSONA_MORAL", "riskLevel": "LOW", "officialMessage": "RFC válido, no susceptible de recibir facturas" }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789002", "processedAt": "2026-03-19T10:01:00-06:00", "billable": true } }, "Risk: CRITICAL": { "summary": "Risk: CRITICAL — RFC not registered in SAT", "value": { "status": "OK", "type": "RFC_NOT_FOUND", "message": "RFC not registered in the SAT taxpayer registry", "data": { "rfc": "GODE881122ZZZ", "isValid": false, "isBillable": false, "taxpayerType": null, "riskLevel": "CRITICAL", "officialMessage": "RFC no registrado en el padrón de contribuyentes" }, "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789003", "processedAt": "2026-03-19T10:02:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "rfc", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'rfc'" }, { "field": "rfc", "code": "INVALID_RFC_FORMAT", "message": "The provided value does not match a valid RFC pattern" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "f1a2b3c4-d5e6-7f8a-9b0c-123456789004", "processedAt": "2026-03-19T10:03: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 } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The SAT validation service is currently unavailable. Please retry.", "data": null, "transactionId": "a87c980d-d5b7-4f7b-a80c-0ec7c78f189c", "processedAt": "2026-05-21T10:00: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": "93819e0c-e88b-4db2-ac75-dcf67f024702", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "validateRfc", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/fiscal/v1/rfc-validations \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"rfc\": \"GARM900101HDF\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/fiscal/v1/rfc-validations\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"rfc\": \"GARM900101HDF\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/fiscal/v1/rfc-validations\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"rfc\": \"GARM900101HDF\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"rfc\\\": \\\"GARM900101HDF\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/fiscal/v1/rfc-validations\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"rfc\": \"GARM900101HDF\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/fiscal/v1/rfc-validations\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"rfc\\\": \\\"GARM900101HDF\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/fiscal/v1/rfc-validations\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/fiscal/v1/csf-extractions": { "post": { "tags": [ "Fiscal" ], "summary": "CSF Data Extraction & Validation (Multi-input)", "description": "**Credits:** 1 per call.\n\nExtracts structured data from a Constancia de Situación Fiscal (CSF) — the official PDF document issued by SAT that proves a taxpayer's fiscal situation. You can submit the CSF as a base64-encoded file (PDF/PNG/JPG) and get back the full content as JSON, or alternatively pass RFC + CIF (the tax-certificate code) to retrieve the same data directly from SAT's public QR validator.\n\nReturns the legal name, address, fiscal regime, economic activities, registration date, and tax obligations. Use this endpoint to automate vendor onboarding and to keep your records of partners' fiscal data continuously up to date.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "string", "description": "Base64 file (PDF/PNG/JPG). Required if RFC/CIF are not provided." }, "rfc": { "type": "string", "description": "Taxpayer RFC (12 or 13 characters)." }, "cif": { "type": "string", "description": "Official Tax Certificate Code (8 to 12 digits)." } }, "oneOf": [ { "required": [ "document" ] }, { "required": [ "rfc", "cif" ] } ] }, "examples": { "by_identifiers": { "summary": "By RFC + CIF", "value": { "rfc": "PELJ900101AAA", "cif": "24010199999" } }, "by_document": { "summary": "By document (base64 PDF/PNG/JPG)", "value": { "document": "JVBERi0xLjQKJ...base64 content...UlGCg==" } } } } } }, "responses": { "200": { "description": "All responses are returned with HTTP 200. The JSON payload defines the success or failure of the transaction.", "content": { "application/json": { "examples": { "Success Legal Entity": { "summary": "Success Legal Entity", "value": { "status": "OK", "type": "SUCCESS", "message": "Company information retrieved successfully", "data": { "rfc": "ACM240101A23", "idCif": "24010199999", "taxpayerType": "PERSONA_MORAL", "status": "ACTIVO", "registrationDate": "2024-01-01", "lastStatusChangeDate": "2024-01-01", "personalInfo": { "givenNames": null, "firstSurname": null, "secondSurname": null, "legalName": "ACME DEMO", "legalType": "SOCIEDAD ANONIMA DE CAPITAL VARIABLE", "commercialName": null, "curp": null, "dateOfBirth": null, "constitutionDate": "2024-01-01" }, "addressNormalized": { "street": "AVENIDA EJEMPLO", "exteriorNumber": "61", "interiorNumber": "INTERIOR 901", "neighborhood": "COLONIA EJEMPLO", "zipCode": "11560", "municipality": "MIGUEL HIDALGO", "state": "CIUDAD DE MEXICO", "country": "MEXICO", "betweenStreets": "CALLE PRIMERA Y CALLE SEGUNDA", "email": "juan.perez@example.com" }, "taxRegimes": [ { "description": "Régimen General de Ley Personas Morales", "startDate": "2024-01-01" } ], "economicActivities": [ { "description": "Servicios de consultoria en computación", "percentage": 100, "startDate": "2024-01-01" } ], "taxObligations": [ { "description": "Declaración de proveedores de IVA", "dueDate": "A más tardar el último día del mes inmediato posterior al periodo que corresponda", "startDate": "2024-01-01" }, { "description": "Pago provisional mensual de ISR personas morales régimen general", "dueDate": "A más tardar el día 17 del mes inmediato posterior al periodo que corresponda", "startDate": "2022-01-01" } ] }, "transactionId": "e9df0229-e1ed-4c09-bd57-0ec81ead9744", "processedAt": "2026-03-19T21:05:00-06:00", "billable": true } }, "Success Individual": { "summary": "Success Individual", "value": { "status": "OK", "type": "SUCCESS", "message": "Taxpayer information retrieved successfully", "data": { "rfc": "GARM900101HDF", "idCif": "19080245312", "taxpayerType": "PERSONA_FISICA", "status": "ACTIVO", "registrationDate": "2012-05-10", "lastStatusChangeDate": "2022-01-01", "personalInfo": { "givenNames": "EDUARDO JAVIER", "firstSurname": "TORRES", "secondSurname": "MENDEZ", "legalName": null, "legalType": null, "commercialName": "E-TORRES CONSULTING", "curp": "TOME851015HDFRZN01", "dateOfBirth": "1985-10-15", "constitutionDate": null }, "addressNormalized": { "street": "AVENIDA INSURGENTES SUR", "exteriorNumber": "1602", "interiorNumber": "PISO 4", "neighborhood": "CREDITO CONSTRUCTOR", "zipCode": "03940", "municipality": "BENITO JUAREZ", "state": "CIUDAD DE MEXICO", "country": "MEXICO", "betweenStreets": null, "email": "eduardo.torres@example.com" }, "taxRegimes": [ { "description": "Régimen Simplificado de Confianza", "startDate": "2022-01-01" } ], "economicActivities": [ { "description": "SERVICIOS DE CONSULTORIA EN COMPUTACION", "percentage": 100, "startDate": "2022-01-01" } ], "taxObligations": [] }, "transactionId": "cdf372bf-e169-4db6-93ed-6c883dde3df1", "processedAt": "2026-03-19T21:00:00-06:00", "billable": true } }, "Tax Profile Not Found": { "summary": "Tax Profile Not Found", "value": { "status": "OK", "type": "TAX_PROFILE_NOT_FOUND", "message": "The provided identifiers do not match any SAT record", "data": null, "transactionId": "daa86cff-481d-4724-96d1-63ea1e10e7f3", "processedAt": "2026-03-19T21:10:00-06:00", "billable": true } }, "Document not trusted": { "summary": "Document not trusted", "value": { "status": "OK", "type": "DOCUMENT_NOT_TRUSTED", "message": "Document QR points to an unofficial host", "data": null, "transactionId": "9a4c1e77-2b3d-4f8a-bc1e-6d5f0a2b3c4d", "processedAt": "2026-06-26T16:34:30-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "body", "code": "MISSING_SEARCH_CRITERIA", "message": "must provide either 'document' or both 'rfc' and 'cif'" }, { "field": "body", "code": "MISSING_DEPENDENT_FIELD", "message": "direct-identifier mode requires both rfc and cif (missing: cif)" }, { "field": "rfc", "code": "INVALID_FORMAT", "message": "rfc must be 12 or 13 alphanumeric characters (SAT format)" }, { "field": "cif", "code": "INVALID_FORMAT", "message": "cif must be 8 to 12 digits" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "2193e042-62b4-4197-ae4c-bca518fca008", "processedAt": "2026-03-19T21:15:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "f7a8b9c0-d1e2-3456-7890-abcdef012345", "processedAt": "2026-03-19T21:16:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The SAT infrastructure is currently unavailable. Please retry.", "data": null, "transactionId": "097acb01-21a6-4cb1-b8da-b45ab153616b", "processedAt": "2026-03-19T21:17: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": "730e56e7-6815-4fc3-b58f-9db49c12213d", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "extractCsf", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/fiscal/v1/csf-extractions \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"rfc\": \"PELJ900101AAA\", \"cif\": \"24010199999\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/fiscal/v1/csf-extractions\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"rfc\": \"PELJ900101AAA\",\n \"cif\": \"24010199999\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/fiscal/v1/csf-extractions\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"rfc\": \"PELJ900101AAA\",\n \"cif\": \"24010199999\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"rfc\\\": \\\"PELJ900101AAA\\\", \\\"cif\\\": \\\"24010199999\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/fiscal/v1/csf-extractions\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"rfc\": \"PELJ900101AAA\", \"cif\": \"24010199999\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/fiscal/v1/csf-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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"rfc\\\": \\\"PELJ900101AAA\\\", \\\"cif\\\": \\\"24010199999\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/fiscal/v1/csf-extractions\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/fiscal/v1/cfdi-validations": { "post": { "tags": [ "Fiscal" ], "summary": "Validate CFDI (Electronic Invoice)", "description": "**Credits:** 1 per call.\n\nValidates a CFDI (Comprobante Fiscal Digital por Internet) — Mexico's mandatory electronic invoice — by checking its current status with SAT. Returns whether the CFDI is currently valid (`VALID`) or cancelled (`CANCELED`), the cancellation status (e.g. requires receiver acceptance), and the fiscal effect (`INCOME`, `EXPENSE`, `TRANSPORT`, `PAYROLL`, `PAYMENT`).\n\nUse this endpoint when reconciling supplier invoices, processing expense reports, or ensuring that the invoices you receive are real and not later cancelled by the issuer without your knowledge.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "example": "7C8BD4EA-AE86-4CB5-88B8-C6E61E988A8B", "description": "CFDI Folio Fiscal (UUID format 8-4-4-4-12). Required when sending direct identifiers." }, "rfcIssuer": { "type": "string", "example": "PEZJ900514H2A", "description": "RFC of the issuer (12 or 13 chars). Required when sending direct identifiers." }, "rfcReceiver": { "type": "string", "example": "EMP210908DT4", "description": "RFC of the receiver (12 or 13 chars). Required when sending direct identifiers." }, "total": { "type": "string", "example": "18750.00", "description": "Total CFDI amount as decimal string (no currency symbol). Required when sending direct identifiers." }, "document": { "type": "string", "description": "Base64-encoded CFDI document. Accepts the XML invoice or a printable representation (PDF, PNG, JPG) containing the SAT QR code. The format is auto-detected from the payload; the backend derives the identifiers from the XML body or from the embedded QR." } }, "oneOf": [ { "required": [ "uuid", "rfcIssuer", "rfcReceiver", "total" ] }, { "required": [ "document" ] } ] } } } }, "responses": { "200": { "description": "CFDI Validation Result (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success Valid CFDI": { "summary": "Success Valid CFDI", "value": { "status": "OK", "type": "SUCCESS", "message": "CFDI is valid and active", "data": { "uuid": "7C8BD4EA-AE86-4CB5-88B8-C6E61E988A8B", "issuer": { "rfc": "PEZJ900514H2A", "name": "JUAN PEREZ ZUNIGA" }, "receiver": { "rfc": "EMP210908DT4", "name": "EMPRESA, S.A. DE C.V." }, "issueDate": "2020-05-18T16:04:42-06:00", "certificationDate": "2020-05-18T16:18:54-06:00", "pacRfc": "SAT970701NN3", "total": { "amount": "18750.00", "currency": "MXN" }, "effect": "INCOME", "status": "VALID", "cancellationStatus": "CANCELABLE_WITH_ACCEPTANCE", "officialMessage": "Vigente" }, "transactionId": "088a6952-eb77-434d-aeac-0970acdb4b25", "processedAt": "2026-04-26T10:00:00-06:00", "billable": true } }, "CFDI Canceled": { "summary": "CFDI Canceled", "value": { "status": "OK", "type": "CFDI_CANCELED", "message": "CFDI exists but has been canceled", "data": { "uuid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890", "issuer": { "rfc": "PEZJ900514H2A", "name": "JUAN PEREZ ZUNIGA" }, "receiver": { "rfc": "EMP210908DT4", "name": "EMPRESA, S.A. DE C.V." }, "issueDate": "2024-03-10T09:15:00-06:00", "certificationDate": "2024-03-10T09:18:22-06:00", "pacRfc": "SAT970701NN3", "total": { "amount": "12500.00", "currency": "MXN" }, "effect": "INCOME", "status": "CANCELED", "cancellationStatus": "CANCELED_WITH_ACCEPTANCE", "cancellationDate": "2024-04-05T14:22:00-06:00", "officialMessage": "Cancelado con aceptación" }, "transactionId": "8f34d125-7ae8-4183-ac44-0a42a1778ea1", "processedAt": "2026-04-26T10:00:00-06:00", "billable": true } }, "CFDI Not Found": { "summary": "CFDI Not Found", "value": { "status": "OK", "type": "CFDI_NOT_FOUND", "message": "UUID not registered in the SAT verification service", "data": null, "transactionId": "1a542dc6-dfcf-440c-8903-7840bad1f9a8", "processedAt": "2026-04-26T10:00:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "body", "code": "MISSING_SEARCH_CRITERIA", "message": "must provide either 'document' or all of uuid, rfcIssuer, rfcReceiver and total" }, { "field": "body", "code": "MISSING_DEPENDENT_FIELD", "message": "direct-identifier mode requires uuid, rfcIssuer, rfcReceiver and total (missing: rfcIssuer, rfcReceiver, total)" }, { "field": "uuid", "code": "INVALID_FORMAT", "message": "uuid must be a UUID in 8-4-4-4-12 hex format" }, { "field": "rfcIssuer", "code": "INVALID_FORMAT", "message": "rfcIssuer must be 12 or 13 alphanumeric characters (SAT format)" }, { "field": "rfcReceiver", "code": "INVALID_FORMAT", "message": "rfcReceiver must be 12 or 13 alphanumeric characters (SAT format)" }, { "field": "total", "code": "INVALID_FORMAT", "message": "total must be a positive decimal string with up to 6 decimals" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "d526f1fc-14b5-4ffc-9be9-cadffcacc941", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "7f811230-4378-4790-a942-c63b2e2b2d77", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } }, "Service Unavailable": { "summary": "Service Unavailable", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "The SAT verification service is currently unavailable. Please retry.", "data": null, "transactionId": "480a94b0-81c7-4c32-ae7f-e4fbc0a678fc", "processedAt": "2026-04-26T10:00: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": "38f3b4ae-15cf-4b5c-9cad-c060c974dcb3", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "validateCfdi", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/fiscal/v1/cfdi-validations \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"uuid\": \"7C8BD4EA-AE86-4CB5-88B8-C6E61E988A8B\", \"rfcIssuer\": \"PEZJ900514H2A\", \"rfcReceiver\": \"EMP210908DT4\", \"total\": \"18750.00\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/fiscal/v1/cfdi-validations\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"uuid\": \"7C8BD4EA-AE86-4CB5-88B8-C6E61E988A8B\",\n \"rfcIssuer\": \"PEZJ900514H2A\",\n \"rfcReceiver\": \"EMP210908DT4\",\n \"total\": \"18750.00\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/fiscal/v1/cfdi-validations\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"uuid\": \"7C8BD4EA-AE86-4CB5-88B8-C6E61E988A8B\",\n \"rfcIssuer\": \"PEZJ900514H2A\",\n \"rfcReceiver\": \"EMP210908DT4\",\n \"total\": \"18750.00\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"uuid\\\": \\\"7C8BD4EA-AE86-4CB5-88B8-C6E61E988A8B\\\", \\\"rfcIssuer\\\": \\\"PEZJ900514H2A\\\", \\\"rfcReceiver\\\": \\\"EMP210908DT4\\\", \\\"total\\\": \\\"18750.00\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/fiscal/v1/cfdi-validations\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"uuid\": \"7C8BD4EA-AE86-4CB5-88B8-C6E61E988A8B\", \"rfcIssuer\": \"PEZJ900514H2A\", \"rfcReceiver\": \"EMP210908DT4\", \"total\": \"18750.00\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/fiscal/v1/cfdi-validations\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"uuid\\\": \\\"7C8BD4EA-AE86-4CB5-88B8-C6E61E988A8B\\\", \\\"rfcIssuer\\\": \\\"PEZJ900514H2A\\\", \\\"rfcReceiver\\\": \\\"EMP210908DT4\\\", \\\"total\\\": \\\"18750.00\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/fiscal/v1/cfdi-validations\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/banking/v1/cep-validations": { "post": { "tags": [ "Banking" ], "summary": "CEP / SPEI Payment Validation", "description": "**Credits:** 1 per call.\n\nValidates a Mexican SPEI transfer against Banco de México's official **CEP** service (\"Comprobante Electrónico de Pago\") and returns the verified transfer details together with Banxico's cryptographic proof. Use it to confirm that a SPEI payment actually settled, for reconciliation, payout confirmation, or fraud checks on a claimed transfer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Identify the transfer by its tracking key or its reference number (choose the matching request body below), and provide the beneficiary account, bank code and amount to match. When the account is an 18-digit CLABE the bank code is resolved from it automatically; for a card account, include the bank code.", "properties": { "trackingKey": { "type": "string", "description": "Clave de rastreo of the SPEI transfer, assigned by the ordering bank.", "example": "BNET01002026060140000098765" }, "referenceNumber": { "type": "string", "description": "Reference number of the transfer. Use this instead of `trackingKey`.", "example": "7654321" }, "operationDate": { "type": "string", "description": "Operation date of the transfer, ISO `YYYY-MM-DD`.", "example": "2026-06-01" }, "senderBankCode": { "type": "string", "description": "Banxico institution code (5 digits) of the ordering bank. Optional when you send an `orderingAccount` CLABE; required for a card account.", "example": "40014" }, "receiverBankCode": { "type": "string", "description": "Banxico institution code (5 digits) of the beneficiary bank. Optional when you send a `beneficiaryAccount` CLABE; required for a card account.", "example": "40012" }, "beneficiaryAccount": { "type": "string", "description": "Beneficiary account: 18-digit CLABE or 16-digit card number. For a CLABE the bank code is resolved automatically and the control digit is validated.", "example": "012180001234567893" }, "orderingAccount": { "type": "string", "description": "Ordering (sender) account: 18-digit CLABE or 16-digit card number. Use instead of `beneficiaryAccount`.", "example": "014320001234567896" }, "amount": { "type": "string", "description": "Transfer amount to match against the CEP, as a decimal string in MXN.", "example": "1500.00" }, "includePdf": { "type": "boolean", "default": false, "description": "Include the CEP PDF in `files` (kind `document`, `application/pdf`). The XML is always returned for settled payments; the PDF only when this flag is true." } }, "oneOf": [ { "title": "By tracking key", "required": [ "trackingKey", "operationDate", "beneficiaryAccount", "senderBankCode", "amount" ] }, { "title": "By reference number", "required": [ "referenceNumber", "operationDate", "beneficiaryAccount", "senderBankCode", "amount" ] } ] } } } }, "responses": { "200": { "description": "CEP validation result (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success": { "value": { "status": "OK", "type": "SUCCESS", "message": "CEP validated", "data": { "valid": true, "banxicoStatus": "LIQUIDADO", "trackingKey": "BNET01002026060140000098765", "referenceNumber": "7654321", "operationDate": "2026-06-01", "concept": "Pago de servicios", "amount": { "value": "1500.00", "currency": "MXN" }, "sender": { "name": "ANA SOFIA MENDEZ CASTRO", "bankCode": "40014", "bankName": "SANTANDER", "account": "014320001234567896", "accountType": "CLABE", "rfc": "MECA880101QX3" }, "beneficiary": { "name": "JUAN CARLOS RAMIREZ SOLIS", "bankCode": "40012", "bankName": "BBVA BANCOMER", "account": "012180001234567893", "accountType": "CLABE", "rfc": "RASJ900215K46" }, "timeline": { "operatedAt": "2026-06-01T14:23:05-06:00", "receivedAt": null, "settledAt": null, "returnReceivedAt": null, "returnSettledAt": null }, "spei": { "speiKey": "40012", "certificateNumber": "00001000000509876543", "signature": "MIIEpAIBAAKCAQEA9Wn...TRUNCATED_BASE64...fQjtFfiQ==", "cdaChain": "||01|01062026|01062026|142305|40012|SANT...TRUNCATED_BASE64...fQjtFfiQ==" }, "files": [ { "kind": "document", "contentType": "application/xml", "sizeBytes": 1582, "content": "PD94bWwgdmVyc2lvbj0iMS4wI...TRUNCATED_BASE64...JjZXJvPg==" } ] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000001", "processedAt": "2026-06-01T14:23:06-06:00", "billable": true } }, "Success with PDF": { "value": { "status": "OK", "type": "SUCCESS", "message": "CEP validated", "data": { "valid": true, "banxicoStatus": "LIQUIDADO", "trackingKey": "BNET01002026060140000098765", "referenceNumber": "7654321", "operationDate": "2026-06-01", "concept": "Pago de servicios", "amount": { "value": "1500.00", "currency": "MXN" }, "sender": { "name": "ANA SOFIA MENDEZ CASTRO", "bankCode": "40014", "bankName": "SANTANDER", "account": "014320001234567896", "accountType": "CLABE", "rfc": "MECA880101QX3" }, "beneficiary": { "name": "JUAN CARLOS RAMIREZ SOLIS", "bankCode": "40012", "bankName": "BBVA BANCOMER", "account": "012180001234567893", "accountType": "CLABE", "rfc": "RASJ900215K46" }, "timeline": { "operatedAt": "2026-06-01T14:23:05-06:00", "receivedAt": null, "settledAt": null, "returnReceivedAt": null, "returnSettledAt": null }, "spei": { "speiKey": "40012", "certificateNumber": "00001000000509876543", "signature": "MIIEpAIBAAKCAQEA9Wn...TRUNCATED_BASE64...fQjtFfiQ==", "cdaChain": "||01|01062026|01062026|142305|40012|SANT...TRUNCATED_BASE64...fQjtFfiQ==" }, "files": [ { "kind": "document", "contentType": "application/xml", "sizeBytes": 1582, "content": "PD94bWwgdmVyc2lvbj0iMS4wI...TRUNCATED_BASE64...JjZXJvPg==" }, { "kind": "document", "contentType": "application/pdf", "sizeBytes": 48213, "content": "JVBERi0xLjQKJ...TRUNCATED_BASE64...JUVPRg==" } ] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000002", "processedAt": "2026-06-01T14:23:06-06:00", "billable": true } }, "Settled No CEP": { "value": { "status": "OK", "type": "SETTLED_NO_CEP", "message": "Payment settled at Banxico; no CEP document is available", "data": { "valid": true, "banxicoStatus": "LIQUIDADO", "trackingKey": "BNET01002026060140000098765", "referenceNumber": null, "operationDate": "2026-06-01", "concept": null, "amount": { "value": "1500.00", "currency": "MXN" }, "sender": { "name": "ANA SOFIA MENDEZ CASTRO", "bankCode": "40014", "bankName": "SANTANDER", "account": "014320001234567896", "accountType": "CLABE", "rfc": "MECA880101QX3" }, "beneficiary": { "name": "JUAN CARLOS RAMIREZ SOLIS", "bankCode": "40012", "bankName": "BBVA BANCOMER", "account": "012180001234567893", "accountType": "CLABE", "rfc": "RASJ900215K46" }, "timeline": { "operatedAt": null, "receivedAt": "2026-06-01T14:23:05-06:00", "settledAt": "2026-06-01T14:23:07-06:00", "returnReceivedAt": null, "returnSettledAt": null }, "spei": { "speiKey": "40012", "certificateNumber": "00001000000509876543", "signature": "MIIEpAIBAAKCAQEA9Wn...TRUNCATED_BASE64...fQjtFfiQ==", "cdaChain": "||01|01062026|01062026|142305|40012|SANT...TRUNCATED_BASE64...fQjtFfiQ==" }, "files": [] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000003", "processedAt": "2026-06-01T14:23:06-06:00", "billable": true } }, "Transfer Returned": { "value": { "status": "OK", "type": "TRANSFER_RETURNED", "message": "Transfer was located but returned to the ordering party; no CEP document is available", "data": { "valid": false, "banxicoStatus": "DEVUELTO", "trackingKey": "BNET01002026060140000098765", "referenceNumber": null, "operationDate": "2026-06-01", "concept": null, "amount": { "value": "1500.00", "currency": "MXN" }, "sender": { "name": "ANA SOFIA MENDEZ CASTRO", "bankCode": "40014", "bankName": "SANTANDER", "account": "014320001234567896", "accountType": "CLABE", "rfc": "MECA880101QX3" }, "beneficiary": { "name": "JUAN CARLOS RAMIREZ SOLIS", "bankCode": "40012", "bankName": "BBVA BANCOMER", "account": "012180001234567893", "accountType": "CLABE", "rfc": "RASJ900215K46" }, "timeline": { "operatedAt": null, "receivedAt": "2026-06-01T14:23:05-06:00", "settledAt": null, "returnReceivedAt": "2026-06-01T15:10:22-06:00", "returnSettledAt": "2026-06-01T15:10:24-06:00" }, "spei": { "speiKey": "40012", "certificateNumber": "00001000000509876543", "signature": "MIIEpAIBAAKCAQEA9Wn...TRUNCATED_BASE64...fQjtFfiQ==", "cdaChain": "||01|01062026|01062026|142305|40012|SANT...TRUNCATED_BASE64...fQjtFfiQ==" }, "files": [] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000004", "processedAt": "2026-06-01T14:23:06-06:00", "billable": true } }, "Transfer Cancelled": { "value": { "status": "OK", "type": "TRANSFER_CANCELLED", "message": "Transfer was located but cancelled; no CEP document is available", "data": { "valid": false, "banxicoStatus": "CANCELADO", "trackingKey": "BNET01002026060140000098765", "referenceNumber": null, "operationDate": "2026-06-01", "concept": null, "amount": { "value": "1500.00", "currency": "MXN" }, "sender": { "name": "ANA SOFIA MENDEZ CASTRO", "bankCode": "40014", "bankName": "SANTANDER", "account": "014320001234567896", "accountType": "CLABE", "rfc": "MECA880101QX3" }, "beneficiary": { "name": "JUAN CARLOS RAMIREZ SOLIS", "bankCode": "40012", "bankName": "BBVA BANCOMER", "account": "012180001234567893", "accountType": "CLABE", "rfc": "RASJ900215K46" }, "timeline": { "operatedAt": null, "receivedAt": "2026-06-01T14:23:05-06:00", "settledAt": "2026-06-01T14:23:07-06:00", "returnReceivedAt": null, "returnSettledAt": null }, "spei": { "speiKey": "40012", "certificateNumber": "00001000000509876543", "signature": "MIIEpAIBAAKCAQEA9Wn...TRUNCATED_BASE64...fQjtFfiQ==", "cdaChain": "||01|01062026|01062026|142305|40012|SANT...TRUNCATED_BASE64...fQjtFfiQ==" }, "files": [] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000005", "processedAt": "2026-06-01T14:23:06-06:00", "billable": true } }, "Payment Found": { "value": { "status": "OK", "type": "PAYMENT_FOUND", "message": "Payment located at Banxico; see data.banxicoStatus for its state", "data": { "valid": false, "banxicoStatus": "EN PROCESO", "trackingKey": "BNET01002026060140000098765", "referenceNumber": null, "operationDate": "2026-06-01", "concept": null, "amount": { "value": "1500.00", "currency": "MXN" }, "sender": { "name": "ANA SOFIA MENDEZ CASTRO", "bankCode": "40014", "bankName": "SANTANDER", "account": "014320001234567896", "accountType": "CLABE", "rfc": "MECA880101QX3" }, "beneficiary": { "name": "JUAN CARLOS RAMIREZ SOLIS", "bankCode": "40012", "bankName": "BBVA BANCOMER", "account": "012180001234567893", "accountType": "CLABE", "rfc": "RASJ900215K46" }, "timeline": { "operatedAt": null, "receivedAt": "2026-06-01T14:23:05-06:00", "settledAt": null, "returnReceivedAt": null, "returnSettledAt": null }, "spei": { "speiKey": "40012", "certificateNumber": "00001000000509876543", "signature": "MIIEpAIBAAKCAQEA9Wn...TRUNCATED_BASE64...fQjtFfiQ==", "cdaChain": "||01|01062026|01062026|142305|40012|SANT...TRUNCATED_BASE64...fQjtFfiQ==" }, "files": [] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000006", "processedAt": "2026-06-01T14:23:06-06:00", "billable": true } }, "CEP Not Found": { "value": { "status": "OK", "type": "CEP_NOT_FOUND", "message": "No CEP was found at Banxico matching the provided transfer details", "data": null, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000007", "processedAt": "2026-06-01T14:23:06-06:00", "billable": true } }, "Validation Error": { "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "errors": [ { "field": "body", "code": "MISSING_SEARCH_CRITERIA", "message": "must provide either trackingKey or referenceNumber" }, { "field": "beneficiaryAccount", "code": "INVALID_CHECKSUM", "message": "beneficiaryAccount has an invalid CLABE control digit" }, { "field": "receiverBankCode", "code": "INCONSISTENT", "message": "receiverBankCode '40002' does not match the bank of beneficiaryAccount (40012 BBVA BANCOMER)" }, { "field": "senderBankCode", "code": "UNKNOWN_INSTITUTION", "message": "senderBankCode '99999' is not a known Banxico institution code" }, { "field": "operationDate", "code": "DATE_MISMATCH_TRACKING_KEY", "message": "operationDate does not match the date embedded in the tracking key" }, { "field": "body", "code": "UPSTREAM_REJECTED", "message": "Banxico rejected the transfer details" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ], "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000008", "processedAt": "2026-06-01T14:23:06-06:00", "billable": false } }, "Service Unavailable": { "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "Banxico's CEP service is temporarily unavailable. Please retry shortly.", "data": null, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a00000000009", "processedAt": "2026-06-01T14:23:06-06:00", "billable": false } }, "Internal Error": { "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a0000000000a", "processedAt": "2026-06-01T14:23:06-06:00", "billable": false } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CepValidationData" } } } ] } } } }, "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": "fb9c33a5-ee2f-42b2-8467-ff6807e14beb", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "validateCep", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/banking/v1/cep-validations \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"trackingKey\": \"BNET01002026060140000012345\", \"operationDate\": \"2026-06-01\", \"senderBankCode\": \"40012\", \"receiverBankCode\": \"40014\", \"beneficiaryAccount\": \"014180567812345678\", \"amount\": \"1500.00\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/banking/v1/cep-validations\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"trackingKey\": \"BNET01002026060140000012345\",\n \"operationDate\": \"2026-06-01\",\n \"senderBankCode\": \"40012\",\n \"receiverBankCode\": \"40014\",\n \"beneficiaryAccount\": \"014180567812345678\",\n \"amount\": \"1500.00\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/banking/v1/cep-validations\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"trackingKey\": \"BNET01002026060140000012345\",\n \"operationDate\": \"2026-06-01\",\n \"senderBankCode\": \"40012\",\n \"receiverBankCode\": \"40014\",\n \"beneficiaryAccount\": \"014180567812345678\",\n \"amount\": \"1500.00\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"trackingKey\\\": \\\"BNET01002026060140000012345\\\", \\\"operationDate\\\": \\\"2026-06-01\\\", \\\"senderBankCode\\\": \\\"40012\\\", \\\"receiverBankCode\\\": \\\"40014\\\", \\\"beneficiaryAccount\\\": \\\"014180567812345678\\\", \\\"amount\\\": \\\"1500.00\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/banking/v1/cep-validations\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"trackingKey\": \"BNET01002026060140000012345\", \"operationDate\": \"2026-06-01\", \"senderBankCode\": \"40012\", \"receiverBankCode\": \"40014\", \"beneficiaryAccount\": \"014180567812345678\", \"amount\": \"1500.00\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/banking/v1/cep-validations\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"trackingKey\\\": \\\"BNET01002026060140000012345\\\", \\\"operationDate\\\": \\\"2026-06-01\\\", \\\"senderBankCode\\\": \\\"40012\\\", \\\"receiverBankCode\\\": \\\"40014\\\", \\\"beneficiaryAccount\\\": \\\"014180567812345678\\\", \\\"amount\\\": \\\"1500.00\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/banking/v1/cep-validations\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } }, "/mex/social-security/v1/issste-records": { "post": { "tags": [ "Social Security" ], "summary": "ISSSTE Record", "description": "**Credits:** 1 per call.\n\nRetrieves a government worker's full ISSSTE record by CURP — personal data, affiliation, pension regime, positions, contribution history, address, assigned clinic, and the official PDF (always included as base64 in `data.files[]` (kind `document`)).\n\nA retrieved record returns `type: SUCCESS` for an active worker. `PENSIONER`, `SCHOLAR`, `INACTIVE`, and `DECEASED` flag KYC-material standings; when more than one applies, precedence is `DECEASED` > `PENSIONER`/`SCHOLAR` > `INACTIVE`. The raw affiliation status and beneficiary type are always in `data.affiliation`, so new statuses ISSSTE may report never break the contract. `CURP_NOT_FOUND` when the CURP has no ISSSTE record. Dates are ISO `YYYY-MM-DD`; monetary amounts are strings (MXN).\n\n**Field presence:** every field is always present (stable contract) — absent values are `null` (objects/scalars, including empty source strings normalized to `null`) or `[]` (arrays), never omitted. Examples: `pensions` and `family` are `[]` when the worker has none; `terminationDate` and a history row's `endDate` are `null` while ongoing; binary assets in `data.files[]` follow array semantics — only assets actually produced are listed (absent ones omitted, not `null`). Unmigrated placeholder values from ISSSTE (e.g. address `POR ACTUALIZAR`, clinic `FAVOR DE ATENDER A ESTE TRABAJADOR` / clave `0409999`, state `ENTIDAD DESCONOCIDA`) are normalized to `null` (data not yet migrated). ISSSTE only exposes records for titulares (TRABAJADOR/PENSIONISTA/BECARIO); a CURP that is only a dependant (not a titular) returns `CURP_NOT_FOUND`. To retrieve a dependant, query the titular CURP and match `data.family[]` by the dependant CURP. `beneficiaryType` is derived authoritatively from the record (a DIRECT pension means PENSIONISTA even if the document labels them TRABAJADOR); each pension carries a derived `category` (DIRECT/SURVIVOR/INSURANCE/DISABILITY).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "curp" ], "properties": { "curp": { "type": "string", "description": "CURP of the government worker whose ISSSTE record is requested.", "example": "GOTM850312MDFMRX05" } } }, "examples": { "By CURP": { "summary": "By CURP", "value": { "curp": "GOTM850312MDFMRX05" } } } } } }, "responses": { "200": { "description": "ISSSTE record result (Strict Envelope Pattern).", "content": { "application/json": { "examples": { "Success": { "summary": "SUCCESS — active worker (2 positions, 5 family members)", "value": { "status": "OK", "type": "SUCCESS", "message": "Active worker found", "data": { "personalInfo": { "curp": "GOTM850312MDFMRX05", "givenNames": "MARIA FERNANDA", "firstSurname": "GOMEZ", "secondSurname": "TORRES", "rfc": "GOTM850312AB1", "gender": "M", "dateOfBirth": "1985-03-12", "maritalStatus": "CASADO", "nss": "10567890123" }, "affiliation": { "beneficiaryType": "TRABAJADOR", "affiliationStatus": "ACTIVO", "governmentEntryDate": "2008-01-01", "currentPositionStartDate": "2008-01-01", "terminationDate": null }, "pensionRegime": { "seniorityYears": 19, "scheme": "CUENTAS INDIVIDUALES" }, "employment": [ { "agency": "SALUD DE TLAXCALA", "payrollOffice": "SALUD DE TLAXCALA", "startDate": "2008-01-01", "baseSalary": "9611.42", "positionType": "BASE", "totalCompensation": "14937.00", "coverage": "TODOS LOS SEGUROS, PRESTACIONES Y SERVICIOS" }, { "agency": "SERVICIOS DE SALUD DEL IMSS PARA EL BIENESTAR", "payrollOffice": "IMSS BIENESTAR TLAXCALA", "startDate": "2024-03-01", "baseSalary": "10452.54", "positionType": "BASE", "totalCompensation": "29390.20", "coverage": "TODOS LOS SEGUROS, PRESTACIONES Y SERVICIOS" } ], "pensions": [], "contributionHistory": [ { "agency": "SALUD DE TLAXCALA", "payrollOffice": "SALUD DE TLAXCALA", "periodType": "NORMAL", "startDate": "2008-01-01", "endDate": "2010-12-31", "baseSalary": "4450.00" }, { "agency": "SALUD DE TLAXCALA", "payrollOffice": "SALUD DE TLAXCALA", "periodType": "NORMAL", "startDate": "2011-01-01", "endDate": "2012-04-30", "baseSalary": "5570.00" } ], "fovissteHistory": [ { "agency": "SALUD DE TLAXCALA", "payrollOffice": "SALUD DE TLAXCALA", "periodType": "NORMAL", "startDate": "2008-01-01", "endDate": "2010-12-31", "baseSalary": "4450.00" }, { "agency": "SALUD DE TLAXCALA", "payrollOffice": "SALUD DE TLAXCALA", "periodType": "NORMAL", "startDate": "2011-01-01", "endDate": "2012-04-30", "baseSalary": "5570.00" } ], "family": [ { "curp": "GOTL120418HDFMRS00", "firstSurname": "GOMEZ", "secondSurname": "TORRES", "givenNames": "LUIS", "relationship": "HIJO", "status": "ACTIVO", "dateOfBirth": "2012-04-18", "registrationDate": "2012-05-01" }, { "curp": "RASP840912HDFMLD05", "firstSurname": "RAMIREZ", "secondSurname": "SOLIS", "givenNames": "PEDRO", "relationship": "ESPOSO", "status": "ACTIVO", "dateOfBirth": "1984-09-12", "registrationDate": "2010-02-01" } ], "address": { "street": "AVENIDA EJEMPLO", "exteriorNumber": "100", "interiorNumber": null, "neighborhood": "CENTRO", "municipality": "PUEBLA", "state": "PUEBLA", "postalCode": "00000" }, "clinic": { "code": "3620300", "type": "HAE", "name": "PUEBLA, PUE.", "address": "JARDINES DE SAN MANUEL, JARDINES DE SAN MANUEL", "issteDelegation": "DELEGACION ESTATAL EN PUEBLA", "phone": "2222456950" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 207341, "content": "JVBERi0xLjYKJdP0...TRUNCATED_BASE64..." }, { "kind": "face", "contentType": "image/jpeg", "sizeBytes": 8421, "content": "/9j/4AAQSkZJRgABAQEAYABgAAD...TRUNCATED_BASE64.../9k=" } ] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a0000000000b", "processedAt": "2026-06-02T10:00:00-06:00", "billable": true } }, "Inactive": { "summary": "INACTIVE — inactive worker (terminationDate set)", "value": { "status": "OK", "type": "INACTIVE", "message": "Inactive worker found", "data": { "personalInfo": { "curp": "DIMR600724MDFZRS03", "givenNames": "ROSA ELENA", "firstSurname": "DIAZ", "secondSurname": "MORALES", "rfc": "DIMR600724XY2", "gender": "M", "dateOfBirth": "1960-07-24", "maritalStatus": "SOLTERO", "nss": "20987654321" }, "affiliation": { "beneficiaryType": "TRABAJADOR", "affiliationStatus": "INACTIVO", "governmentEntryDate": "1982-10-01", "currentPositionStartDate": "2016-07-31", "terminationDate": "2026-06-02" }, "pensionRegime": { "seniorityYears": 43, "scheme": "CUENTAS INDIVIDUALES" }, "employment": [], "pensions": [], "contributionHistory": [ { "agency": "INST. DE SEG. Y SERVS. SOCLS. DE LOS TRABJS. DEL EDO. (ISSST", "payrollOffice": "ISSSTE. DIRECCION DE ADMINISTRACION", "periodType": "NORMAL", "startDate": "2021-03-01", "endDate": "2023-01-15", "baseSalary": "4448.50" }, { "agency": "INST. DE SEG. Y SERVS. SOCLS. DE LOS TRABJS. DEL EDO. (ISSST", "payrollOffice": "ISSSTE. DIRECCION DE ADMINISTRACION", "periodType": "CERTIFICADO DyE", "startDate": "2023-01-16", "endDate": "2023-10-15", "baseSalary": "9077.00" } ], "fovissteHistory": [ { "agency": "INST. DE SEG. Y SERVS. SOCLS. DE LOS TRABJS. DEL EDO. (ISSST", "payrollOffice": "ISSSTE. DIRECCION DE ADMINISTRACION", "periodType": "NORMAL", "startDate": "2021-03-01", "endDate": "2023-01-15", "baseSalary": "4448.50" }, { "agency": "INST. DE SEG. Y SERVS. SOCLS. DE LOS TRABJS. DEL EDO. (ISSST", "payrollOffice": "ISSSTE. DIRECCION DE ADMINISTRACION", "periodType": "CERTIFICADO DyE", "startDate": "2023-01-16", "endDate": "2023-10-15", "baseSalary": "9077.00" } ], "family": [], "address": { "street": "AVENIDA EJEMPLO", "exteriorNumber": "100", "interiorNumber": null, "neighborhood": "CENTRO", "municipality": "TIJUANA", "state": "BAJA CALIFORNIA", "postalCode": "00000" }, "clinic": { "code": "0220800", "type": "CMF", "name": "MESA DE OTAY", "address": null, "issteDelegation": "DELEGACION ESTATAL EN BAJA CALIFORNIA", "phone": null }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 207341, "content": "JVBERi0xLjYKJdP0...TRUNCATED_BASE64..." }, { "kind": "face", "contentType": "image/jpeg", "sizeBytes": 8421, "content": "/9j/4AAQSkZJRgABAQEAYABgAAD...TRUNCATED_BASE64.../9k=" } ] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a0000000000c", "processedAt": "2026-06-02T10:00:00-06:00", "billable": true } }, "Deceased": { "summary": "DECEASED — deceased worker (survivor pension + family)", "value": { "status": "OK", "type": "DECEASED", "message": "Deceased worker found", "data": { "personalInfo": { "curp": "RUVC550415MDFZGR07", "givenNames": "CARMEN", "firstSurname": "RUIZ", "secondSurname": "VEGA", "rfc": "RUVC550415PQ3", "gender": "M", "dateOfBirth": "1955-04-15", "maritalStatus": "SOLTERO", "nss": "30135792468" }, "affiliation": { "beneficiaryType": "TRABAJADOR", "affiliationStatus": "FINADO", "governmentEntryDate": "1987-11-16", "currentPositionStartDate": "2022-08-24", "terminationDate": null }, "pensionRegime": { "seniorityYears": 0, "scheme": "DÉCIMO TRANSITORIO" }, "employment": [], "pensions": [ { "category": "SURVIVOR", "agency": "PENSIONISTAS Y JUBILADOS CON CARGO AL I.S.S.S.T.E.", "payrollOffice": "I.S.S.S.T.E. PENSIONISTAS DEUDOS GUANAJUATO", "startDate": "2022-08-24", "pensionNumber": "9000000", "pensionType": "316", "pensionAmount": 25731.3 } ], "contributionHistory": [ { "agency": "SECRETARIA DE EDUCACION EN GUANAJUATO-UNIDAD PUENTECILLAS", "payrollOffice": "SECRETARIA DE EDUCACION EN GUANAJUATO-UNIDAD PUENTECILLAS", "periodType": "PENSIONES", "startDate": "1987-11-16", "endDate": "1987-12-15", "baseSalary": "168.75" }, { "agency": "SECRETARIA DE EDUCACION EN GUANAJUATO-UNIDAD PUENTECILLAS", "payrollOffice": "SECRETARIA DE EDUCACION EN GUANAJUATO-UNIDAD PUENTECILLAS", "periodType": "PENSIONES", "startDate": "1987-12-16", "endDate": "1987-12-31", "baseSalary": "194.10" } ], "fovissteHistory": [ { "agency": "SECRETARIA DE EDUCACION EN GUANAJUATO-UNIDAD PUENTECILLAS", "payrollOffice": "SECRETARIA DE EDUCACION EN GUANAJUATO-UNIDAD PUENTECILLAS", "periodType": "PENSIONES", "startDate": "1987-11-16", "endDate": "1987-12-15", "baseSalary": "168.75" }, { "agency": "SECRETARIA DE EDUCACION EN GUANAJUATO-UNIDAD PUENTECILLAS", "payrollOffice": "SECRETARIA DE EDUCACION EN GUANAJUATO-UNIDAD PUENTECILLAS", "periodType": "PENSIONES", "startDate": "1987-12-16", "endDate": "1987-12-31", "baseSalary": "194.10" } ], "family": [ { "curp": "GOTA140722MDFMRN06", "firstSurname": "GOMEZ", "secondSurname": "TORRES", "givenNames": "ANA", "relationship": "HIJA", "status": "POSIBLE DEUDO", "dateOfBirth": "2014-07-22", "registrationDate": "2014-08-01" } ], "address": { "street": "AVENIDA EJEMPLO", "exteriorNumber": "100", "interiorNumber": null, "neighborhood": "CENTRO", "municipality": "CELAYA", "state": "GUANAJUATO", "postalCode": "00000" }, "clinic": { "code": "1120700", "type": "CH", "name": "CELAYA", "address": "AV. EL SAUZ ESQ. ESMERALDA, SANJUANICO", "issteDelegation": "DELEGACION ESTATAL EN GUANAJUATO", "phone": "4616141390" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 209880, "content": "JVBERi0xLjYKJdP0...TRUNCATED_BASE64..." }, { "kind": "face", "contentType": "image/jpeg", "sizeBytes": 8421, "content": "/9j/4AAQSkZJRgABAQEAYABgAAD...TRUNCATED_BASE64.../9k=" } ] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a0000000000d", "processedAt": "2026-06-02T10:00:00-06:00", "billable": true } }, "Pensioner": { "summary": "PENSIONER — real direct pensioner (own retirement pension; web miscategorized as TRABAJADOR, corrected to PENSIONISTA)", "value": { "status": "OK", "type": "PENSIONER", "message": "Pensioner found", "data": { "personalInfo": { "curp": "SOLE600705MVZTRL01", "givenNames": "ELENA", "firstSurname": "SOTO", "secondSurname": "LARA", "rfc": "SOLE600705RS4", "gender": "M", "dateOfBirth": "1960-07-05", "maritalStatus": "CASADO", "nss": "40246813579" }, "affiliation": { "beneficiaryType": "PENSIONISTA", "affiliationStatus": "ACTIVO", "governmentEntryDate": "1979-10-01", "currentPositionStartDate": "2010-01-01", "terminationDate": null }, "pensionRegime": { "seniorityYears": 0, "scheme": "DÉCIMO TRANSITORIO" }, "employment": [], "pensions": [ { "category": "DIRECT", "agency": "PENSIONISTAS Y JUBILADOS CON CARGO AL I.S.S.S.T.E.", "payrollOffice": "I.S.S.S.T.E. PENSIONISTAS DIRECTOS VERACRUZ", "startDate": "2010-01-01", "pensionNumber": "9000000", "pensionType": "101", "pensionAmount": 9720.9 } ], "contributionHistory": [ { "agency": "SECRETARIA DE EDUCACION PUBLICA (SEP)", "payrollOffice": "GOBIERNO DEL ESTADO DE VERACRUZ, SISTEMA EDUCATIVO ESTATAL.", "periodType": "PENSIONES", "startDate": "1993-06-16", "endDate": "1994-09-30", "baseSalary": "1575.15" }, { "agency": "SECRETARIA DE EDUCACION Y CULTURA DEL ESTADO DE VERACRUZ", "payrollOffice": "SECRETARIA DE EDUCACION Y CULTURA DEL ESTADO DE VERACRUZ", "periodType": "PENSIONES", "startDate": "1979-10-01", "endDate": "1979-12-31", "baseSalary": "4.14" } ], "fovissteHistory": [ { "agency": "SECRETARIA DE EDUCACION PUBLICA (SEP)", "payrollOffice": "GOBIERNO DEL ESTADO DE VERACRUZ, SISTEMA EDUCATIVO ESTATAL.", "periodType": "PENSIONES", "startDate": "1993-06-16", "endDate": "1994-09-30", "baseSalary": "1575.15" }, { "agency": "SECRETARIA DE EDUCACION Y CULTURA DEL ESTADO DE VERACRUZ", "payrollOffice": "SECRETARIA DE EDUCACION Y CULTURA DEL ESTADO DE VERACRUZ", "periodType": "PENSIONES", "startDate": "1979-10-01", "endDate": "1979-12-31", "baseSalary": "4.14" } ], "family": [ { "curp": "TOVR550130MDFRGS02", "firstSurname": "TORRES", "secondSurname": "VEGA", "givenNames": "ROSA", "relationship": "MADRE", "status": "ACTIVO", "dateOfBirth": "1955-01-30", "registrationDate": "2009-03-10" }, { "curp": "GOLJ521105HDFMRS07", "firstSurname": "GOMEZ", "secondSurname": "LARA", "givenNames": "JOSE", "relationship": "PADRE", "status": "ACTIVO", "dateOfBirth": "1952-11-05", "registrationDate": "2009-03-10" } ], "address": { "street": "AVENIDA EJEMPLO", "exteriorNumber": "100", "interiorNumber": null, "neighborhood": "CENTRO", "municipality": "HUATUSCO", "state": "VERACRUZ", "postalCode": "00000" }, "clinic": { "code": "3020601", "type": "UMF", "name": "HUATUSCO DE CHICUELLAR", "address": "CALLE 2, CENTRO", "issteDelegation": "DELEGACION ESTATAL EN VERACRUZ", "phone": "273 100 8334" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 209880, "content": "JVBERi0xLjYKJdP0...TRUNCATED_BASE64..." }, { "kind": "face", "contentType": "image/jpeg", "sizeBytes": 8421, "content": "/9j/4AAQSkZJRgABAQEAYABgAAD...TRUNCATED_BASE64.../9k=" } ] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a0000000000e", "processedAt": "2026-06-02T10:00:00-06:00", "billable": true } }, "Scholar": { "summary": "SCHOLAR — CONAHCYT/SECIHTI grant holder", "value": { "status": "OK", "type": "SCHOLAR", "message": "Scholarship holder found", "data": { "personalInfo": { "curp": "MERC900821HDFNSR06", "givenNames": "CARLOS", "firstSurname": "MENDEZ", "secondSurname": "RIOS", "rfc": "MERC900821TU5", "gender": "H", "dateOfBirth": "1990-08-21", "maritalStatus": "SOLTERO", "nss": "50369258147" }, "affiliation": { "beneficiaryType": "BECARIO", "affiliationStatus": "ACTIVO", "governmentEntryDate": "2024-02-01", "currentPositionStartDate": "2026-02-16", "terminationDate": null }, "pensionRegime": { "seniorityYears": 1, "scheme": "CUENTAS INDIVIDUALES" }, "employment": [ { "agency": "SECRETARIA DE CIENCIA, HUMANIDADES, TECNOLOGIA E INNOVACION", "payrollOffice": "SECRETARIA DE CIENCIA, HUMANIDADES, TECNOLOGIA E INOVACION (BECARIOS)", "startDate": "2025-12-01", "baseSalary": "21397.32", "positionType": "BECARIO", "totalCompensation": "21397.32", "coverage": "SEGURO DE SALUD (SOLO SERVICIO MEDICO)" }, { "agency": "SECRETARIA DE EDUCACION PUBLICA (SEP)", "payrollOffice": "TECNOLOGICO NACIONAL DE MEXICO", "startDate": "2026-02-16", "baseSalary": "9451.20", "positionType": "BASE", "totalCompensation": "10400.52", "coverage": "TODOS LOS SEGUROS, PRESTACIONES Y SERVICIOS" } ], "pensions": [], "contributionHistory": [ { "agency": "CONSEJO NACIONAL DE HUMANIDADES, CIENCIAS Y TECNOLOGIAS", "payrollOffice": "CONSEJO NACIONAL DE HUMANIDADES, CIENCIAS Y TECNOLOGIAS (BECARIOS)", "periodType": "CERTIFICADO DyE", "startDate": "2025-04-01", "endDate": "2025-12-31", "baseSalary": "8364.00" }, { "agency": "SECRETARIA DE CIENCIA, HUMANIDADES, TECNOLOGIA E INNOVACION", "payrollOffice": "SECRETARIA DE CIENCIA, HUMANIDADES, TECNOLOGIA E INOVACION (BECARIOS)", "periodType": "CERTIFICADO DyE", "startDate": "2025-12-01", "endDate": null, "baseSalary": "21397.32" } ], "fovissteHistory": [ { "agency": "CONSEJO NACIONAL DE HUMANIDADES, CIENCIAS Y TECNOLOGIAS", "payrollOffice": "CONSEJO NACIONAL DE HUMANIDADES, CIENCIAS Y TECNOLOGIAS (BECARIOS)", "periodType": "CERTIFICADO DyE", "startDate": "2025-04-01", "endDate": "2025-12-31", "baseSalary": "8364.00" }, { "agency": "SECRETARIA DE CIENCIA, HUMANIDADES, TECNOLOGIA E INNOVACION", "payrollOffice": "SECRETARIA DE CIENCIA, HUMANIDADES, TECNOLOGIA E INOVACION (BECARIOS)", "periodType": "CERTIFICADO DyE", "startDate": "2025-12-01", "endDate": null, "baseSalary": "21397.32" } ], "family": [], "address": { "street": "AVENIDA EJEMPLO", "exteriorNumber": "100", "interiorNumber": null, "neighborhood": "CENTRO", "municipality": "MERIDA", "state": "YUCATAN", "postalCode": "00000" }, "clinic": { "code": "3120100", "type": "CMFE", "name": "MERIDA (COL. LINDAVISTA)", "address": "19B POR 44 Y 44A, PEDREGALES DE LINDAVISTA", "issteDelegation": "DELEGACION ESTATAL EN YUCATAN", "phone": "9999421470" }, "files": [ { "kind": "document", "contentType": "application/pdf", "sizeBytes": 207341, "content": "JVBERi0xLjYKJdP0...TRUNCATED_BASE64..." }, { "kind": "face", "contentType": "image/jpeg", "sizeBytes": 8421, "content": "/9j/4AAQSkZJRgABAQEAYABgAAD...TRUNCATED_BASE64.../9k=" } ] }, "transactionId": "0a1b2c3d-4e5f-4a6b-8c9d-a0000000000f", "processedAt": "2026-06-02T10:00:00-06:00", "billable": true } }, "CURP Not Found": { "summary": "CURP valid but not registered in ISSSTE (billable)", "value": { "status": "OK", "type": "CURP_NOT_FOUND", "message": "CURP not found in ISSSTE", "data": null, "transactionId": "c1d2e3f4-a5b6-7c8d-9e0f-222222222222", "processedAt": "2026-06-01T11:00:00-06:00", "billable": true } }, "Validation Error": { "summary": "Validation Error", "value": { "status": "ERROR", "type": "INVALID_REQUEST", "message": "Validation failed", "data": null, "transactionId": "c1d2e3f4-a5b6-7c8d-9e0f-444444444444", "processedAt": "2026-06-01T11:00:00-06:00", "billable": false, "errors": [ { "field": "curp", "code": "MISSING_REQUIRED_FIELD", "message": "must have required property 'curp'" }, { "field": "curp", "code": "INVALID_FORMAT", "message": "curp must be a valid 18-character CURP" }, { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds the maximum allowed size" } ] } }, "Service Unavailable": { "summary": "ISSSTE portal unavailable or blocked", "value": { "status": "ERROR", "type": "SERVICE_UNAVAILABLE", "message": "ISSSTE service is currently unavailable", "data": null, "transactionId": "c1d2e3f4-a5b6-7c8d-9e0f-555555555555", "processedAt": "2026-06-01T11:00:00-06:00", "billable": false } }, "Internal Error": { "summary": "Internal Error", "value": { "status": "ERROR", "type": "INTERNAL_ERROR", "message": "Unexpected internal error", "data": null, "transactionId": "c1d2e3f4-a5b6-7c8d-9e0f-666666666666", "processedAt": "2026-06-01T11:00:00-06:00", "billable": false } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IssteRecordData" } } } ] } } } }, "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": "fb9c33a5-ee2f-42b2-8467-ff6807e14beb", "processedAt": "2026-04-26T10:00:00-06:00", "billable": false } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "operationId": "getIssteRecord", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST https://api.origoid.com/mex/social-security/v1/issste-records \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -H \"content-type: application/json\" \\\n -d '{\"curp\": \"TEST900101HDFRRN09\"}'" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://api.origoid.com/mex/social-security/v1/issste-records\", {\n method: \"POST\",\n headers: {\n \"x-api-key\": process.env.ORIGOID_API_KEY,\n \"content-type\": \"application/json\",\n },\n body: JSON.stringify({\n \"curp\": \"TEST900101HDFRRN09\"\n }),\n});\n\nif (!response.ok) {\n throw new Error(`HTTP ${response.status}`);\n}\n\nconst result = await response.json();\nconsole.log(result);" }, { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.origoid.com/mex/social-security/v1/issste-records\",\n headers={\n \"x-api-key\": os.environ[\"ORIGOID_API_KEY\"],\n \"content-type\": \"application/json\",\n },\n json={\n \"curp\": \"TEST900101HDFRRN09\"\n },\n timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)" }, { "lang": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Example {\n public static void main(String[] args) throws Exception {\n String payload = \"{\\\"curp\\\": \\\"TEST900101HDFRRN09\\\"}\";\n\n HttpClient client = HttpClient.newBuilder()\n .connectTimeout(Duration.ofSeconds(10))\n .build();\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.origoid.com/mex/social-security/v1/issste-records\"))\n .header(\"x-api-key\", System.getenv(\"ORIGOID_API_KEY\"))\n .header(\"content-type\", \"application/json\")\n .timeout(Duration.ofSeconds(30))\n .POST(HttpRequest.BodyPublishers.ofString(payload))\n .build();\n\n HttpResponse response = client.send(\n request, HttpResponse.BodyHandlers.ofString()\n );\n\n System.out.println(response.statusCode());\n System.out.println(response.body());\n }\n}" }, { "lang": "PHP", "source": " true,\n CURLOPT_POSTFIELDS => $payload,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'x-api-key: ' . getenv('ORIGOID_API_KEY'),\n 'content-type: application/json',\n ],\n]);\n\n$response = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) {\n throw new Exception(\"HTTP $status\");\n}\n\n$result = json_decode($response, true);\nprint_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(`{\"curp\": \"TEST900101HDFRRN09\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://api.origoid.com/mex/social-security/v1/issste-records\", 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;\nusing System.Net.Http;\nusing System.Text;\nusing System.Threading.Tasks;\n\nclass Program\n{\n static async Task Main()\n {\n using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\n client.DefaultRequestHeaders.Add(\"x-api-key\",\n Environment.GetEnvironmentVariable(\"ORIGOID_API_KEY\"));\n\n var payload = \"{\\\"curp\\\": \\\"TEST900101HDFRRN09\\\"}\";\n var content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\n var response = await client.PostAsync(\"https://api.origoid.com/mex/social-security/v1/issste-records\", content);\n response.EnsureSuccessStatusCode();\n\n var body = await response.Content.ReadAsStringAsync();\n Console.WriteLine(body);\n }\n}" } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "BasicAuth": { "type": "http", "scheme": "basic" } }, "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." } } }, "CepValidationData": { "type": "object", "nullable": true, "description": "Verified SPEI transfer details from the CEP. Null for non-located outcomes (`CEP_NOT_FOUND`) and error types.", "properties": { "valid": { "type": "boolean", "description": "Whether the transfer is a confirmed, settled payment. True for LIQUIDADO; false for returned, cancelled or in-process.", "example": true }, "banxicoStatus": { "type": "string", "description": "Raw Banxico payment state. Known values: `LIQUIDADO`, `DEVUELTO`, `CANCELADO`, `EN PROCESO`. Branch on `type`; use this for display.", "example": "LIQUIDADO" }, "trackingKey": { "type": "string", "description": "Clave de rastreo of the transfer.", "example": "BNET01002026060140000098765" }, "referenceNumber": { "type": "string", "nullable": true, "description": "Reference number, when present in the CEP.", "example": "7654321" }, "operationDate": { "type": "string", "format": "date", "description": "Business operation date (ISO `YYYY-MM-DD`). The calendar date used to match; see `timeline.operatedAt` for the exact instant.", "example": "2026-06-01" }, "concept": { "type": "string", "nullable": true, "description": "Payment concept, when present.", "example": "Pago de servicios" }, "amount": { "type": "object", "description": "Transfer amount. `value` is a decimal string, exact to the cent; currency is always MXN.", "properties": { "value": { "type": "string", "example": "1500.00" }, "currency": { "type": "string", "enum": [ "MXN" ], "example": "MXN" } } }, "sender": { "type": "object", "nullable": true, "description": "Ordering (sender) party. Fields may be null when Banxico does not expose them (for non-settled results).", "properties": { "name": { "type": "string", "nullable": true, "example": "ANA SOFIA MENDEZ CASTRO" }, "bankCode": { "type": "string", "nullable": true, "description": "Banxico institution code (5 digits).", "example": "40014" }, "bankName": { "type": "string", "nullable": true, "example": "SANTANDER" }, "account": { "type": "string", "nullable": true, "example": "014320001234567896" }, "accountType": { "type": "string", "nullable": true, "enum": [ "CLABE", "CARD" ], "description": "Inferred from the account number (18-digit CLABE or 16-digit card).", "example": "CLABE" }, "rfc": { "type": "string", "nullable": true, "description": "RFC as printed in the CEP, when present.", "example": "MECA880101QX3" } } }, "beneficiary": { "type": "object", "nullable": true, "description": "Beneficiary party. Fields may be null when Banxico does not expose them (for non-settled results).", "properties": { "name": { "type": "string", "nullable": true, "example": "JUAN CARLOS RAMIREZ SOLIS" }, "bankCode": { "type": "string", "nullable": true, "description": "Banxico institution code (5 digits).", "example": "40012" }, "bankName": { "type": "string", "nullable": true, "example": "BBVA BANCOMER" }, "account": { "type": "string", "nullable": true, "example": "012180001234567893" }, "accountType": { "type": "string", "nullable": true, "enum": [ "CLABE", "CARD" ], "description": "Inferred from the account number (18-digit CLABE or 16-digit card).", "example": "CLABE" }, "rfc": { "type": "string", "nullable": true, "description": "RFC as printed in the CEP, when present.", "example": "RASJ900215K46" } } }, "timeline": { "type": "object", "description": "Transfer lifecycle timestamps, ISO 8601 in `America/Mexico_City` (`-06:00`), second precision. Null where not applicable to the result.", "properties": { "operatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Instant the transfer was operated (from the CEP).", "example": "2026-06-01T14:23:05-06:00" }, "receivedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Instant SPEI received the payment order.", "example": null }, "settledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Instant SPEI settled the payment (liquidación).", "example": null }, "returnReceivedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Instant the return order was received.", "example": null }, "returnSettledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Instant the return was settled.", "example": null } } }, "spei": { "type": "object", "description": "SPEI / Banxico cryptographic proof carried by the CEP (the digital signature that makes the CEP verifiable).", "properties": { "speiKey": { "type": "string", "nullable": true, "description": "Clave SPEI (operating-institution code).", "example": "40012" }, "certificateNumber": { "type": "string", "nullable": true, "example": "00001000000509876543" }, "signature": { "type": "string", "nullable": true, "description": "Base64 digital signature from Banxico.", "example": "MIIEpAIBAAKCAQEA9Wn...TRUNCATED_BASE64...fQjtFfiQ==" }, "cdaChain": { "type": "string", "nullable": true, "description": "Original signed CDA chain (the string Banxico signed).", "example": "||01|01062026|...TRUNCATED_BASE64...fQjtFfiQ==" } } }, "files": { "type": "array", "description": "CEP documents as inline base64 assets. The XML (`application/xml`) is present for settled payments; the PDF (`application/pdf`) is included only when `includePdf` is true. Empty for non-settled results.", "items": { "$ref": "#/components/schemas/Asset" } } } }, "FaceMatchData": { "type": "object", "nullable": true, "description": "Face-match result. Null for `INVALID_REQUEST` and `INTERNAL_ERROR`.", "properties": { "faceMatchScore": { "type": "number", "nullable": true, "description": "Similarity 0-100. Null when the score was not the basis of the result (DOCUMENT_MISMATCH, NO_DOCUMENT_DETECTED, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED) — anti-leak of signal.", "example": 96.4 }, "isMatch": { "type": "boolean", "example": true }, "thresholdApplied": { "type": "integer", "nullable": true, "description": "Threshold used for the decision. Null when not applied (non-match outcomes).", "example": 90 }, "detectedDocumentType": { "type": "string", "nullable": true, "description": "Document type classified from the front image (e.g. `INE`, `MEX_PASSPORT`, `OTHER`). Null in some non-match cases.", "example": "INE" }, "selfieAnalysis": { "type": "object", "nullable": true, "description": "Quality/attribute labels of the selfie face (DX-friendly, no raw scores). Null when there is no single selfie face (NO_FACE_DETECTED on selfie, MULTIPLE_FACES_DETECTED).", "properties": { "imageQuality": { "type": "string", "enum": [ "excellent", "good", "poor" ], "example": "excellent" }, "detectionConfidence": { "type": "string", "enum": [ "high", "medium", "low" ], "example": "high" }, "orientation": { "type": "string", "enum": [ "front", "looking_left", "looking_right", "looking_up", "looking_down", "tilted", "sideways" ], "example": "front" }, "eyesOpen": { "type": "boolean", "example": true }, "mouthOpen": { "type": "boolean", "example": false }, "wearingGlasses": { "type": "boolean", "example": false }, "wearingSunglasses": { "type": "boolean", "example": false }, "faceCovered": { "type": "boolean", "example": false }, "issues": { "type": "array", "description": "Actionable retry hints. Subset of the catalog.", "items": { "type": "string", "enum": [ "wearing_glasses", "wearing_sunglasses", "face_covered", "eyes_closed", "poor_image_quality", "not_facing_camera", "low_detection_confidence" ] }, "example": [] } } } } }, "LivenessData": { "type": "object", "nullable": true, "description": "Liveness result. Null for `INVALID_REQUEST`, `INTERNAL_ERROR` and `SERVICE_UNAVAILABLE`. On every `OK` outcome the object is present: when nothing could be evaluated (`NO_FACE_DETECTED`, `MULTIPLE_FACES_DETECTED`, `IMAGE_UNREADABLE`) `isLive` is `false` and the remaining fields are null.", "properties": { "isLive": { "type": "boolean", "description": "`true` when `livenessScore` reaches the decision threshold (62). Always present; `false` when the image was not evaluated.", "example": true }, "livenessScore": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100, "description": "Fused anti-spoofing score, 0–100. Null when the image was not evaluated.", "example": 98 }, "confidence": { "type": "string", "nullable": true, "enum": [ "HIGH", "MEDIUM", "LOW" ], "description": "Distance of the score from the decision threshold: `HIGH` 25 points or more, `MEDIUM` 10 or more, `LOW` otherwise. Null when the image was not evaluated.", "example": "HIGH" }, "selfieAnalysis": { "type": "object", "nullable": true, "description": "Quality/attribute labels of the evaluated face — the largest face when `allowMultipleFaces` is true. Same shape as `matchFaces`. Null when the image was not evaluated or when face analysis was unavailable.", "properties": { "imageQuality": { "type": "string", "enum": [ "excellent", "good", "poor" ], "example": "excellent", "description": "`excellent`: brightness ≥ 75 and sharpness ≥ 75 · `good`: both ≥ 50 · `poor`: otherwise (in practice, usually a dark image rather than an out-of-focus one)." }, "detectionConfidence": { "type": "string", "enum": [ "high", "medium", "low" ], "example": "high", "description": "Provider confidence that the detection is a face: `high` ≥ 95 · `medium` ≥ 80 · `low` below 80." }, "orientation": { "type": "string", "enum": [ "front", "looking_left", "looking_right", "looking_up", "looking_down", "tilted", "sideways" ], "example": "front", "description": "Evaluated in order, first match wins: `sideways` abs(yaw) ≥ 25° · `looking_left` yaw ≥ 10° · `looking_right` yaw ≤ −10° · `looking_up` pitch ≥ 20° · `looking_down` pitch ≤ −20° · `tilted` abs(roll) ≥ 15° · otherwise `front`." }, "eyesOpen": { "type": "boolean", "nullable": true, "description": "Null when the attribute could not be determined.", "example": true }, "mouthOpen": { "type": "boolean", "nullable": true, "description": "Informational; never produces an issue. Null when the attribute could not be determined.", "example": false }, "wearingGlasses": { "type": "boolean", "nullable": true, "description": "Null when the attribute could not be determined.", "example": false }, "wearingSunglasses": { "type": "boolean", "nullable": true, "description": "Null when the attribute could not be determined.", "example": false }, "faceCovered": { "type": "boolean", "nullable": true, "description": "Null when the attribute could not be determined.", "example": false }, "issues": { "type": "array", "description": "Every condition detected on the face; empty when none. All possible values: `poor_image_quality` (`imageQuality` is `poor`) · `not_facing_camera` (`orientation` is not `front`) · `eyes_closed` (`eyesOpen` is `false`) · `face_covered` (`faceCovered` is `true`) · `wearing_glasses` (`wearingGlasses` is `true`, informational) · `wearing_sunglasses` (`wearingSunglasses` is `true`) · `low_detection_confidence` (`detectionConfidence` is `low`). Retry hints, not rejection criteria.", "items": { "type": "string", "enum": [ "wearing_glasses", "wearing_sunglasses", "face_covered", "eyes_closed", "poor_image_quality", "not_facing_camera", "low_detection_confidence" ] }, "example": [] } } } } }, "Asset": { "type": "object", "description": "Binary asset (image or document) returned inline as base64. The `files` array contains ONLY assets actually produced; an expected-but-unavailable asset is omitted (never null inside the array).", "required": [ "kind", "contentType", "sizeBytes", "content" ], "properties": { "kind": { "type": "string", "description": "Semantic asset name (e.g. document, face, signature)." }, "contentType": { "type": "string", "description": "MIME type (e.g. application/pdf, image/jpeg, application/xml)." }, "sizeBytes": { "type": "integer", "description": "Decoded size in bytes." }, "content": { "type": "string", "description": "Base64-encoded bytes." } } }, "IssteRecordData": { "type": "object", "description": "Full ISSSTE record for a government worker. Present only when `type` is `SUCCESS`.", "properties": { "personalInfo": { "type": "object", "properties": { "curp": { "type": "string", "example": "GOTM850312MDFMRX05" }, "givenNames": { "type": "string", "example": "MARIA FERNANDA" }, "firstSurname": { "type": "string", "example": "GOMEZ" }, "secondSurname": { "type": "string", "example": "TORRES" }, "rfc": { "type": "string", "description": "RFC as printed in the record. May be incomplete (10-char base without homoclave) or empty when the source PDF omits it.", "example": "GOTM850312AB1" }, "gender": { "type": "string", "enum": [ "H", "M" ], "description": "Normalized from source HOMBRE/MUJER.", "example": "M" }, "dateOfBirth": { "type": "string", "format": "date", "description": "ISO `YYYY-MM-DD` (normalized from source DD/MM/YYYY).", "example": "1985-03-12" }, "maritalStatus": { "type": "string", "nullable": true, "enum": [ "SOLTERO", "CASADO", "DIVORCIADO", "VIUDO", "UNION_LIBRE" ], "description": "Civil status, normalized (source prints a gender-neutral '(A)' suffix, removed here). `null` when ISSSTE does not report it. Only SOLTERO/CASADO seen in the current corpus.", "example": "SOLTERO" }, "nss": { "type": "string", "description": "Social security number (NSS).", "example": "10567890123" } } }, "affiliation": { "type": "object", "properties": { "beneficiaryType": { "type": "string", "enum": [ "TRABAJADOR", "PENSIONISTA", "BECARIO" ], "description": "Authoritative standing, derived from the record: a holder of a DIRECT pension is reported as PENSIONISTA even when the source document labels them TRABAJADOR. ISSSTE only exposes titulares.", "example": "TRABAJADOR" }, "affiliationStatus": { "type": "string", "enum": [ "ACTIVO", "INACTIVO", "FINADO", "" ], "description": "Raw official value. Empty string when not reported.", "example": "ACTIVO" }, "governmentEntryDate": { "type": "string", "format": "date", "nullable": true, "description": "Date the worker entered federal government employment (ISO).", "example": "2014-09-01" }, "currentPositionStartDate": { "type": "string", "format": "date", "nullable": true, "example": "2018-07-01" }, "terminationDate": { "type": "string", "format": "date", "nullable": true, "description": "`null` while `ACTIVO`; set for `INACTIVO`/`FINADO`.", "example": null } } }, "pensionRegime": { "type": "object", "properties": { "seniorityYears": { "type": "integer", "nullable": true, "description": "Years of seniority (parsed from the source `N año(s)`). `null` when not reported.", "example": 10 }, "scheme": { "type": "string", "enum": [ "CUENTAS INDIVIDUALES", "DÉCIMO TRANSITORIO", "SIN RÉGIMEN", "" ], "description": "Raw official pension regime.", "example": "CUENTAS INDIVIDUALES" } } }, "employment": { "type": "array", "description": "Worker positions (PLAZAS TRABAJADOR). Empty for PENSIONISTA or INACTIVO without an active position.", "items": { "type": "object", "properties": { "agency": { "type": "string", "description": "Ramo / government agency.", "example": "SECRETARIA DE HACIENDA Y CREDITO PUBLICO (SHCP)" }, "payrollOffice": { "type": "string", "description": "Pagaduría.", "example": "SHCP. SERVICIO DE ADMINISTRACION TRIBUTARIA" }, "startDate": { "type": "string", "format": "date", "example": "2018-07-01" }, "baseSalary": { "type": "string", "description": "Salario base de cotización (MXN).", "example": "9451.20" }, "positionType": { "type": "string", "description": "Tipo de plaza/pensión (e.g. CONFIANZA, BECARIO).", "example": "CONFIANZA" }, "totalCompensation": { "type": "string", "description": "Remuneración total (MXN).", "example": "22590.16" }, "coverage": { "type": "string", "description": "Modalidad de seguros/prestaciones (source field `modilidad` [sic] corrected to `coverage`).", "example": "TODOS LOS SEGUROS, PRESTACIONES Y SERVICIOS" } } } }, "pensions": { "type": "array", "description": "Pension records (survivor/retirement pensions, PENSIONES). Empty when none.", "items": { "type": "object", "properties": { "category": { "type": "string", "nullable": true, "enum": [ "DIRECT", "SURVIVOR", "INSURANCE", "DISABILITY" ], "description": "Derived pension class from the payroll office: DIRECT (own retirement, pagaduria DIRECTOS), SURVIVOR (deudos), INSURANCE (cuenta individual aseguradora), DISABILITY (ITP/IPP).", "example": "DIRECT" }, "agency": { "type": "string", "example": "PENSIONISTAS Y JUBILADOS CON CARGO AL I.S.S.S.T.E." }, "payrollOffice": { "type": "string", "example": "I.S.S.S.T.E. PENSIONISTAS DEUDOS GUANAJUATO" }, "startDate": { "type": "string", "format": "date", "example": "2022-08-24" }, "pensionNumber": { "type": "string", "example": "9000000" }, "pensionType": { "type": "string", "description": "Numeric ISSSTE pension-type code (e.g. `101` retirement, `316` survivor). 21+ codes.", "example": "316" }, "pensionAmount": { "type": "number", "description": "Monthly pension amount (MXN).", "example": 25731.3 } } } }, "contributionHistory": { "type": "array", "description": "Contribution (cotización) timeline. May be empty for `INACTIVO` without archived data.", "items": { "type": "object", "properties": { "agency": { "type": "string", "example": "SECRETARIA DE HACIENDA Y CREDITO PUBLICO (SHCP)" }, "payrollOffice": { "type": "string", "example": "SHCP. SERVICIO DE ADMINISTRACION TRIBUTARIA" }, "periodType": { "type": "string", "example": "NORMAL" }, "startDate": { "type": "string", "format": "date", "example": "2014-09-01" }, "endDate": { "type": "string", "format": "date", "nullable": true, "example": "2016-05-17" }, "baseSalary": { "type": "string", "description": "Sueldo básico (MXN).", "example": "5906.45" } } } }, "fovissteHistory": { "type": "array", "description": "FOVISSSTE contribution history (housing fund) — HISTORIAL DE COTIZACIÓN FOVISSSTE. Same shape as contributionHistory; may mirror it or be a subset.", "items": { "type": "object", "properties": { "agency": { "type": "string", "example": "SECRETARIA DE HACIENDA Y CREDITO PUBLICO (SHCP)" }, "payrollOffice": { "type": "string", "example": "SHCP. SERVICIO DE ADMINISTRACION TRIBUTARIA" }, "periodType": { "type": "string", "example": "NORMAL" }, "startDate": { "type": "string", "format": "date", "example": "2014-09-01" }, "endDate": { "type": "string", "format": "date", "nullable": true, "example": "2016-05-17" }, "baseSalary": { "type": "string", "description": "Sueldo básico (MXN).", "example": "5906.45" } } } }, "family": { "type": "array", "description": "Registered family members / dependants (FAMILIARES). Empty when none.", "items": { "type": "object", "properties": { "curp": { "type": "string", "example": "GOTL120418HDFMRS00" }, "firstSurname": { "type": "string", "example": "GOMEZ" }, "secondSurname": { "type": "string", "example": "TORRES" }, "givenNames": { "type": "string", "example": "LUIS" }, "relationship": { "type": "string", "enum": [ "HIJO", "HIJA", "ESPOSO", "ESPOSA", "CONCUBINA", "CONCUBINO", "MADRE", "PADRE", "ABUELA", "ABUELO", "HIJA DE CONYUGE" ], "description": "Parentesco (official raw value).", "example": "HIJO" }, "status": { "type": "string", "enum": [ "ACTIVO", "SIN DERECHO", "EN CONSERVACIÓN DE DERECHOS", "POSIBLE DEUDO" ], "description": "Derechohabiencia status of the family member (raw).", "example": "ACTIVO" }, "dateOfBirth": { "type": "string", "format": "date", "example": "2012-04-18" }, "registrationDate": { "type": "string", "format": "date", "description": "Fecha de alta as a dependant.", "example": "2012-05-01" } } } }, "address": { "type": "object", "description": "Domicilio.", "properties": { "street": { "type": "string", "example": "AVENIDA EJEMPLO" }, "exteriorNumber": { "type": "string", "example": "100" }, "interiorNumber": { "type": "string", "nullable": true, "example": "A" }, "neighborhood": { "type": "string", "description": "Colonia.", "example": "CENTRO" }, "municipality": { "type": "string", "description": "Delegación / municipio.", "example": "CUAUHTEMOC" }, "state": { "type": "string", "example": "CIUDAD DE MEXICO" }, "postalCode": { "type": "string", "example": "00000" } } }, "clinic": { "type": "object", "description": "Assigned medical unit (clínica de adscripción).", "properties": { "code": { "type": "string", "description": "Clave.", "example": "9121200" }, "type": { "type": "string", "enum": [ "CMF", "UMF", "CMFE", "CH", "CAF", "HAE", "HG", "CMFEQ" ], "description": "Medical-unit type (raw).", "example": "CMF" }, "name": { "type": "string", "example": "JUAREZ" }, "address": { "type": "string", "example": "JALAPA Nº 252, ROMA" }, "issteDelegation": { "type": "string", "example": "DELEGACION EN LA ZONA NORTE DE LA CDMX" }, "phone": { "type": "string", "description": "May be `NO DISPONIBLE` or comma-separated numbers.", "example": "55-84-49-81,55-74-13-19" } } }, "files": { "type": "array", "description": "Binary assets (inline base64). The document (PDF) is always present. A face is included only when the record contains a usable face; it is omitted when no face is present or its quality is too low.", "items": { "$ref": "#/components/schemas/Asset" } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "BasicAuth": [] } ] }