{"components":{"schemas":{"Certificate":{"properties":{"cer_base64":{"description":"Base64 DER of the .cer file. Null when SAT's CDN did not serve it.","type":["string","null"]},"curp":{"description":"Persona física certs only","type":["string","null"]},"email":{"type":["string","null"]},"legal_representative_curp":{"description":"Persona moral certs only","type":["string","null"]},"legal_representative_rfc":{"description":"Persona moral certs only","type":["string","null"]},"serial":{"description":"20-digit SAT certificate serial number","type":"string"},"status":{"description":"Activo, Caduco, or Revocado","type":"string"},"type":{"description":"FIEL (e.firma) or SELLO (CSD)","type":"string"},"valid_from_utc":{"format":"date-time","type":"string"},"valid_to_utc":{"format":"date-time","type":"string"}},"type":"object"},"CfdiRecord":{"description":"A CFDI as SAT's Verifica CFDI portal prints it. Values are the portal's text, unparsed; blank cells are null.","properties":{"efecto_comprobante":{"description":"Voucher type: Ingreso, Egreso, Traslado, Nómina, or Pago.","example":"Ingreso","type":["string","null"]},"es_cancelable":{"description":"Whether and how the CFDI can be cancelled.","example":"Cancelable sin aceptación","type":["string","null"]},"estado":{"description":"SAT's state, unchanged: Vigente or Cancelado.","example":"Vigente","type":["string","null"]},"estatus_cancelacion":{"description":"Cancellation request status, when one exists.","type":["string","null"]},"fecha_cancelacion":{"description":"Cancellation date, when cancelled.","type":["string","null"]},"fecha_certificacion":{"description":"Stamping (certification) date, SAT's format, no time zone.","example":"2024-05-06T17:46:06","type":["string","null"]},"fecha_emision":{"description":"Issue date, SAT's format, no time zone.","example":"2024-05-06T17:45:57","type":["string","null"]},"folio_sustitucion":{"description":"UUID of the replacing CFDI, for reason 01.","type":["string","null"]},"motivo":{"description":"Cancellation reason code (01–04), when cancelled.","type":["string","null"]},"nombre_emisor":{"description":"Issuer name as SAT prints it.","example":"ACME CONSULTORES","type":["string","null"]},"nombre_receptor":{"description":"Receiver name as SAT prints it.","example":"PUBLICO EN GENERAL","type":["string","null"]},"rfc_emisor":{"description":"Issuer RFC.","example":"ACM010101AAA","type":["string","null"]},"rfc_pac":{"description":"RFC of the PAC that stamped the CFDI.","example":"ACM010101AAA","type":["string","null"]},"rfc_receptor":{"description":"Receiver RFC.","example":"XAXX010101000","type":["string","null"]},"sello_cfdi":{"description":"Issuer seal verdict (e.g. Válido). Only for XML uploads.","type":["string","null"]},"sello_timbre_fiscal":{"description":"Stamp seal verdict (e.g. Válido). Only for XML uploads.","type":["string","null"]},"total":{"description":"Total as SAT prints it, currency-formatted.","example":"$1,000.00","type":["string","null"]},"uuid":{"description":"Folio fiscal (UUID).","example":"5FB2822E-396D-4725-8521-CDC4BDD20CCF","type":["string","null"]}},"type":"object"},"CsfTaxpayer":{"description":"A taxpayer as a Constancia de Situación Fiscal describes it. Dates are ISO 8601; other values are SAT's text. Fields that only one kind of taxpayer or one source has are omitted rather than null.","properties":{"address":{"description":"Fiscal address (domicilio fiscal).","properties":{"and_street":{"description":"Second cross street. Only in `document.data`.","example":"CALLE DOS","type":["string","null"]},"between_street":{"description":"First cross street. Only in `document.data`.","example":"CALLE UNO","type":["string","null"]},"exterior_number":{"description":"Número exterior.","example":"200","type":["string","null"]},"interior_number":{"description":"Número interior.","type":["string","null"]},"locality":{"description":"Localidad. Only in `document.data`.","example":"CUAUHTEMOC","type":["string","null"]},"municipality":{"description":"Municipio or demarcación territorial.","example":"CUAUHTEMOC","type":["string","null"]},"neighborhood":{"description":"Colonia.","example":"COLONIA DE EJEMPLO","type":["string","null"]},"state":{"description":"Entidad federativa.","example":"CIUDAD DE MEXICO","type":["string","null"]},"street":{"description":"Nombre de vialidad.","example":"AVENIDA DE EJEMPLO","type":["string","null"]},"street_type":{"description":"Tipo de vialidad.","example":"CALLE","type":["string","null"]},"tax_office":{"description":"SAT's local administration (AL). Only in `taxpayer`.","example":"CIUDAD DE MEXICO 1","type":["string","null"]},"zip":{"description":"Postal code.","example":"06600","type":["string","null"]}},"type":"object"},"birthdate":{"description":"Persona física only. Only in `taxpayer`.","example":"1980-01-01","type":["string","null"]},"capital_regime":{"description":"Persona moral only.","example":"SA DE CV","type":["string","null"]},"curp":{"description":"Persona física only.","example":"PEMJ800101HDFRRN07","type":["string","null"]},"economic_activities":{"description":"Economic activities the constancia prints. Only in `document.data`.","items":{"properties":{"activity":{"description":"Activity name.","example":"Servicios de consultoría en computación","type":["string","null"]},"end_date":{"description":"End date; null while current.","type":["string","null"]},"order":{"description":"SAT's order number.","type":"integer"},"percentage":{"description":"Share of income, 0-100.","type":"integer"},"start_date":{"description":"Start date.","example":"2001-01-01","type":["string","null"]}},"type":"object"},"type":"array"},"email":{"description":"Contact email, when SAT prints one.","type":["string","null"]},"incorporation_date":{"description":"Persona moral only. Only in `taxpayer`.","example":"2001-01-01","type":["string","null"]},"mothers_maiden_name":{"description":"Persona física only.","example":"MARTINEZ","type":["string","null"]},"name":{"description":"Full name, or the company's denominación or razón social.","example":"ACME CONSULTORES","type":["string","null"]},"names":{"description":"Given names. Persona física only.","example":"JUAN CARLOS","type":["string","null"]},"obligations":{"description":"Tax obligations the constancia prints: the returns and payments the taxpayer must file. Only in `document.data`.","items":{"properties":{"description":{"description":"The obligation.","example":"Pago definitivo mensual de IVA.","type":["string","null"]},"due":{"description":"When it falls due, in SAT's words.","example":"A más tardar el día 17 del mes inmediato posterior al periodo que corresponda.","type":["string","null"]},"end_date":{"description":"End date; null while current.","type":["string","null"]},"start_date":{"description":"Start date.","example":"2001-01-01","type":["string","null"]}},"type":"object"},"type":"array"},"paternal_surname":{"description":"Persona física only.","example":"PEREZ","type":["string","null"]},"person_type":{"enum":["fisica","moral"],"type":"string"},"regimes":{"description":"Tax regimes. `taxpayer` lists the current ones.","items":{"properties":{"end_date":{"description":"End date; null while current.","type":["string","null"]},"name":{"description":"Regime name.","example":"Régimen General de Ley Personas Morales","type":["string","null"]},"start_date":{"description":"Start date.","example":"2001-01-01","type":["string","null"]}},"type":"object"},"type":"array"},"start_date":{"description":"Start date of operations (fecha de inicio de operaciones).","example":"2001-01-01","type":["string","null"]},"status":{"description":"Status in the registry (estatus en el padrón).","example":"ACTIVO","type":["string","null"]},"status_date":{"description":"Date of the last status change.","example":"2001-01-01","type":["string","null"]},"trade_name":{"description":"Nombre comercial. Only in `document.data`.","example":"ACME","type":["string","null"]}},"type":"object"},"CurpIdentity":{"properties":{"associated_curps":{"description":"CURPs listed in the PDF's correction section. Included by default on CURP lookup/search. Empty array when none are listed; null when the document could not be read.","items":{"type":"string"},"type":["array","null"]},"birthdate":{"description":"DD/MM/YYYY","type":"string"},"certification":{"description":"Certification statement printed on the official PDF. Included by default on CURP lookup/search. Null when no statement is printed or the document could not be read.","example":"CURP Certificada: verificada con el Registro Civil","type":["string","null"]},"certified":{"description":"true when the official PDF prints a CURP certification statement (Registro Civil, SRE, or INM); false when the PDF was read successfully and no statement is present; null when the document could not be read. This is not a nationality or paperwork eligibility determination.","type":["boolean","null"]},"curp":{"type":"string"},"entity_birth":{"type":"string"},"homonimo":{"example":false,"type":"boolean"},"mothers_maiden_name":{"type":"string"},"names":{"type":"string"},"nationality":{"type":"string"},"paternal_surname":{"type":"string"},"probation_document":{"type":["string","null"]},"probation_document_data":{"type":"object"},"renapo_valid":{"type":"boolean"},"sex":{"type":"string"},"status_curp":{"type":"string"}},"type":"object"},"Error":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"type":"object"},"IneCredential":{"description":"The record INE returned for the credential, with INE's own field names.","properties":{"anio_emision":{"type":["string","null"]},"anio_registro":{"type":["string","null"]},"cic":{"type":["string","null"]},"clave_elector":{"type":["string","null"]},"distrito_federal":{"type":["string","null"]},"distrito_local":{"type":["string","null"]},"en_lista_nominal":{"type":["boolean","null"]},"en_padron_electoral":{"type":["boolean","null"]},"fecha_actualizacion":{"description":"When INE last updated the record, local time without offset.","type":["string","null"]},"fecha_consulta":{"format":"date","type":["string","null"]},"found":{"type":"boolean"},"mensaje":{"description":"INE's headline sentence, in Spanish.","type":["string","null"]},"modelo":{"enum":["d","e"],"type":"string"},"numero_emision":{"type":["string","null"]},"ocr":{"type":["string","null"]},"puede_votar":{"description":"True only when INE also places the holder in the Lista Nominal.","type":["boolean","null"]},"status":{"type":"string"},"vigencia":{"description":"Expiry date.","format":"date","type":["string","null"]},"vigente":{"description":"INE reports the credential as valid identification.","type":["boolean","null"]}},"type":"object"},"LegalRepresentative":{"properties":{"associated_curps":{"description":"CURPs listed in the PDF's correction section. Included by default on CURP lookup/search. Empty array when none are listed; null when the document could not be read.","items":{"type":"string"},"type":["array","null"]},"birthdate":{"description":"DD/MM/YYYY","type":"string"},"certification":{"description":"Certification statement printed on the official PDF. Included by default on CURP lookup/search. Null when no statement is printed or the document could not be read.","example":"CURP Certificada: verificada con el Registro Civil","type":["string","null"]},"certified":{"description":"true when the official PDF prints a CURP certification statement (Registro Civil, SRE, or INM); false when the PDF was read successfully and no statement is present; null when the document could not be read. This is not a nationality or paperwork eligibility determination.","type":["boolean","null"]},"curp":{"type":"string"},"entity_birth":{"type":"string"},"homonimo":{"example":false,"type":"boolean"},"mothers_maiden_name":{"type":"string"},"names":{"type":"string"},"nationality":{"type":"string"},"paternal_surname":{"type":"string"},"probation_document":{"type":["string","null"]},"probation_document_data":{"type":"object"},"renapo_valid":{"type":"boolean"},"sex":{"type":"string"},"status_curp":{"type":"string"}},"type":"object"},"SatListing":{"properties":{"article":{"description":"Article: 69, 69b, 69b_bis","type":"string"},"first_publication_date":{"description":"Date SAT first published the listing, when the list provides one","type":"string"},"name":{"type":"string"},"person_type":{"description":"M (moral) or F (física)","type":"string"},"situation":{"type":"string"},"state":{"type":"string"},"sub_list":{"description":"e.g. cancelados, firmes, no_localizados","type":"string"}},"type":"object"},"WebhookAccepted":{"properties":{"message":{"type":"string"},"status":{"example":"processing","type":"string"}},"type":"object"}},"securitySchemes":{"apiKey":{"description":"API key for authenticating requests. Generate keys from your dashboard after signing up.","in":"header","name":"x-api-key","type":"apiKey"}}},"externalDocs":{"description":"Full developer documentation","url":"https://mexcheck.com/docs"},"info":{"contact":{"email":"help@mexcheck.com","name":"MexCheck Support","url":"https://mexcheck.com/docs"},"description":"One REST API for Mexican identity and tax checks, on one API key and one credit balance. Each endpoint asks the registry that owns the data and returns its answer.\n\n## Endpoints by registry\n\n- SAT: `/rfc/validate`, `/rfc/profile`, `/rfc/find-zip`, `/rfc/verify`, `/rfc/sat-lists`, `/rfc/verify-batch` (RFC registration, taxpayer data, postal code, certificates, SAT lists), `/cfdi/verify` (whether an invoice is current or cancelled), and `/csf/verify` (a Constancia de Situación Fiscal read and checked). Documented on RFCCheck.\n- RENAPO: `/curp/lookup` and `/curp/search` (CURP identity). Documented on CURPCheck.\n- INE: `/ine/verify` (whether a voter ID is current). Documented on INECheck.\n- CFE: `/cfe/verify` (whether CFE issued an electricity receipt, with the address on CFE's own copy). Documented on MexCheck.\n- Correos de México: `/geo/zip` and `/geo/zip-search` (zip codes and the settlements they serve). Documented on MexCheck.\n\nRFCCheck, CURPCheck, and INECheck are MexCheck's single-product sites; accounts, keys, and balance are shared across all four domains.","termsOfService":"https://mexcheck.com/terms-and-conditions","title":"MexCheck API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/cfdi/verify":{"post":{"description":"Asks SAT's Verifica CFDI portal whether a CFDI (factura) is registered and whether it is current or cancelled. Send either the folio search (`uuid`, `rfc_emisor`, `rfc_receptor`) or the CFDI itself as `xml`, never both. Upload the XML file as multipart/form-data (`curl -F xml=@factura.xml`), or send it as a string in a JSON body. Sending the XML also has SAT check the CFDI's seals (`sello_cfdi`, `sello_timbre_fiscal`). An answer without a record (`found: false`) costs 5 credits; `found: null` means SAT could not be reached and is not charged. ~3 s.","externalDocs":{"description":"Endpoint guide","url":"https://rfccheck.com/docs/endpoints/cfdi-verify"},"operationId":"cfdiVerify","requestBody":{"content":{"application/json":{"example":{"rfc_emisor":"ACM010101AAA","rfc_receptor":"XAXX010101000","uuid":"5FB2822E-396D-4725-8521-CDC4BDD20CCF"},"schema":{"oneOf":[{"properties":{"rfc_emisor":{"description":"RFC of the issuer (emisor).","example":"ACM010101AAA","type":"string"},"rfc_receptor":{"description":"RFC of the receiver (receptor).","example":"XAXX010101000","type":"string"},"uuid":{"description":"Folio fiscal (UUID) of the CFDI, any case.","example":"5FB2822E-396D-4725-8521-CDC4BDD20CCF","format":"uuid","type":"string"}},"required":["uuid","rfc_emisor","rfc_receptor"],"title":"Folio search","type":"object"},{"properties":{"xml":{"description":"The CFDI XML document as a string, as stamped by the PAC (with its tfd:TimbreFiscalDigital).","type":"string"}},"required":["xml"],"title":"XML upload","type":"object"}]}},"multipart/form-data":{"schema":{"properties":{"xml":{"contentMediaType":"application/xml","description":"The CFDI XML file as stamped by the PAC (with its tfd:TimbreFiscalDigital).","type":"string"}},"required":["xml"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"cfdi":{"anyOf":[{"$ref":"#/components/schemas/CfdiRecord"},{"type":"null"}]},"found":{"description":"true = SAT returned the CFDI in `cfdi`; false = SAT answered without one (charged); null = SAT unreachable (not charged).","type":["boolean","null"]},"message":{"description":"Plain-language summary. For `no_encontrado` and `rechazado` it is SAT's own message, in Spanish.","type":"string"},"status":{"description":"`vigente` or `cancelado` when found, `no_encontrado` when SAT has no such CFDI, `rechazado` when the portal refused the request itself (e.g. an XML it could not read), null when `found` is null. A status SAT adds later is passed through lowercased, so treat unknown values as neither current nor cancelled.","examples":["vigente","cancelado","no_encontrado","rechazado"],"type":["string","null"]},"uuid":{"description":"Folio fiscal asked about, uppercased. For an XML upload it is read from the stamp; null when the XML carries none and SAT found nothing.","type":["string","null"]}},"type":"object"}}},"description":"Lookup completed. `found` is true / false / null."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to `invalid_fields` and `fields` listing every missing or malformed field. Sending both the folio fields and `xml` lists the ones sent."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Verify a CFDI with SAT"}},"/cfe/verify":{"post":{"description":"Checks a CFE electricity receipt (recibo de luz), the usual proof of address, with CFE. Send `file` (the PDF CFE hands out, a scan, or a PNG/JPEG photo; upload it as multipart/form-data with `curl -F file=@recibo.pdf`, or send it as base64 in JSON), or `service_number`, `name`, and `total` as the receipt prints them. With a file, any of the three values also sent replaces what was read from it. CFE confirms that the three belong together and hands over its own copy of the receipt, returned as `receipt`. For a file, `document` adds what the file prints, the differences from CFE's copy, and `alert`. A PDF is read whole and compared field by field; a photo or scan is read from its payment barcode (service number, due date, amount) and by OCR (holder, address), and only the barcode's fields are compared. An answer where CFE refuses the values (`found: false`) costs 50 credits; `found: null` means CFE could not be asked and is not charged. 2–10 s.","externalDocs":{"description":"Endpoint guide","url":"https://mexcheck.com/docs/endpoints/cfe-verify"},"operationId":"cfeVerify","requestBody":{"content":{"application/json":{"example":{"name":"JUAN PEREZ LOPEZ","service_number":"123456789012","total":63},"schema":{"properties":{"file":{"contentEncoding":"base64","description":"The receipt as base64: CFE's PDF, a scan, or a PNG or JPEG photo that shows the payment barcode. A `data:` URL prefix is accepted. Up to 8 MB. Send this, or the three values below.","type":"string"},"name":{"description":"The holder's name exactly as the receipt prints it, cut short if the receipt cuts it short.","example":"JUAN PEREZ LOPEZ","type":"string"},"service_number":{"description":"The 12-digit service number (No. de servicio).","example":"123456789012","type":"string"},"total":{"description":"The amount to pay (Total a pagar) in whole pesos.","example":63,"type":"integer"}},"type":"object"}},"multipart/form-data":{"schema":{"properties":{"file":{"contentMediaType":"application/pdf","description":"The receipt file: CFE's PDF, a scan, or a PNG or JPEG photo. Up to 8 MB.","type":"string"},"name":{"description":"Optional: the holder's name, instead of the one read.","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"document":{"description":"The file that was sent. Null without a file.","properties":{"age_days":{"description":"Days since the receipt fell due, in Mexico City's calendar; negative while it is not yet due.","type":["integer","null"]},"alert":{"description":"`edited`: the file differs from CFE's copy of the same bill. `outdated_or_edited`: it differs from another bill of the service.","enum":["edited","outdated_or_edited",null],"type":["string","null"]},"compared":{"description":"The fields compared with CFE's copy.","items":{"type":"string"},"type":"array"},"data":{"description":"What the file prints. For a photo, the fields outside the barcode, the holder and the address are null.","properties":{"account":{"example":"01DD00A000000000","type":["string","null"]},"address":{"description":"The address of the service, line by line as printed.","example":["AV. SIEMPRE VIVA 742","COL. CENTRO &C.P.64000","MONTERREY, N.L.,N.L."],"items":{"type":"string"},"type":"array"},"due_date":{"example":"2026-11-16","format":"date","type":["string","null"]},"meter":{"example":"ZZZ000","type":["string","null"]},"name":{"description":"The holder, as printed.","example":"JUAN PEREZ LOPEZ","type":["string","null"]},"period_end":{"example":"2026-10-29","format":"date","type":["string","null"]},"period_start":{"example":"2026-08-28","format":"date","type":["string","null"]},"service_number":{"example":"123456789012","type":["string","null"]},"tariff":{"example":"1C","type":["string","null"]},"total":{"description":"The amount to pay, in whole pesos.","example":63,"type":["integer","null"]},"zip":{"example":"64000","type":["string","null"]}},"type":"object"},"differences":{"description":"The compared fields that differ from CFE's copy.","items":{"type":"string"},"type":"array"},"matches_cfe":{"type":["boolean","null"]},"same_receipt":{"description":"Whether CFE's copy is the same bill as the file.","type":["boolean","null"]},"source":{"enum":["pdf","photo"],"type":"string"}},"type":["object","null"]},"found":{"type":["boolean","null"]},"message":{"description":"A sentence on the result. When `found` is false, CFE's own words, followed by a note when the receipt fell due more than 120 days ago and may only be too old to check.","type":["string","null"]},"mismatch":{"description":"When `found` is false, the value CFE refused. `total`: the amount is not that of the service's last two receipts, the only ones CFE confirms, so a genuine receipt from months ago is refused the same way. Null when CFE's answer names neither, as for an unknown service number.","enum":["name","total",null],"type":["string","null"]},"receipt":{"description":"CFE's own copy of the receipt: the one for the month of the file when CFE still lists it, otherwise the latest.","properties":{"account":{"example":"01DD00A000000000","type":["string","null"]},"address":{"description":"The address of the service, line by line as the receipt prints it. Null when only CFE's record of the bill could be read.","example":["AV. SIEMPRE VIVA 742","COL. CENTRO &C.P.64000","MONTERREY, N.L.,N.L."],"items":{"type":"string"},"type":["array","null"]},"address_parts":{"description":"The same address from CFE's record of the bill, in parts. Null when CFE did not hand the record over. CFE writes accented letters and Ñ as `?`; the letter is put back from the printed receipt when it is there.","properties":{"between_street":{"example":"ENTRE UNO Y DOS","type":["string","null"]},"city":{"description":"The town, as CFE writes it.","example":"MONTERREY","type":["string","null"]},"municipality":{"description":"From the zip code catalogue, when it has the zip code under `municipality_code`. Null otherwise.","example":"Monterrey","type":["string","null"]},"municipality_code":{"description":"The municipality's INEGI code within its state.","example":"039","type":["string","null"]},"neighborhood":{"description":"The colonia.","example":"COL. CENTRO","type":["string","null"]},"state":{"description":"The state's name from the zip code catalogue, when it has the zip code under `municipality_code`; otherwise CFE's abbreviation (`N.L.`).","example":"Nuevo León","type":["string","null"]},"state_code":{"description":"The state's INEGI code, from the zip code catalogue. Null otherwise.","example":"19","type":["string","null"]},"street":{"description":"Street and number.","example":"AV. SIEMPRE VIVA 742","type":["string","null"]},"zip":{"example":"64000","type":["string","null"]}},"type":["object","null"]},"due_date":{"example":"2026-11-16","format":"date","type":["string","null"]},"meter":{"example":"ZZZ000","type":["string","null"]},"name":{"description":"The holder, as printed.","example":"JUAN PEREZ LOPEZ","type":["string","null"]},"period_end":{"example":"2026-10-29","format":"date","type":["string","null"]},"period_start":{"example":"2026-08-28","format":"date","type":["string","null"]},"service_number":{"example":"123456789012","type":["string","null"]},"tariff":{"example":"1C","type":["string","null"]},"total":{"description":"The amount to pay, in whole pesos.","example":63,"type":["integer","null"]},"zip":{"example":"64000","type":["string","null"]}},"type":["object","null"]},"service_number":{"example":"123456789012","type":"string"}},"type":"object"}}},"description":"CFE's answer. `found` is true when CFE confirms the values, false when it refuses them, and null when CFE could not be asked."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to `invalid_fields` and `fields` listing every missing or malformed field. A file that is not a CFE receipt, or a photo without its payment barcode, lists `file`; a photo whose holder could not be read lists `name`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Verify a CFE electricity receipt"}},"/csf/verify":{"post":{"description":"Reads a Constancia de Situación Fiscal (CSF) and checks it with SAT's QR validator. Send one of: `file` (the constancia PDF, or a PNG/JPEG of it; upload it as multipart/form-data with `curl -F file=@constancia.pdf`, or send it as base64 in JSON), `qr` (the text of a QR code printed on the constancia, or an array with both), or `rfc` with `id_cif`. `taxpayer` is SAT's record today: fiscal address, regimes, and start date of operations. For a file, `document` adds what the PDF prints (including economic activities), whether SAT confirms it issued the constancia and when, and the differences between the PDF and SAT's current record. An answer without a record (`found: false`) costs 5 credits; `found: null` means SAT could not be reached and is not charged. ~2 s.","externalDocs":{"description":"Endpoint guide","url":"https://rfccheck.com/docs/endpoints/csf-verify"},"operationId":"csfVerify","requestBody":{"content":{"application/json":{"example":{"id_cif":"10010100002","rfc":"ACME010101AAA"},"schema":{"oneOf":[{"properties":{"id_cif":{"description":"The idCIF printed under the taxpayer's name on the constancia's first page.","example":"10010100002","type":"string"},"rfc":{"description":"The taxpayer's RFC.","example":"ACME010101AAA","type":"string"}},"required":["rfc","id_cif"],"title":"RFC and idCIF","type":"object"},{"properties":{"qr":{"description":"The text of a QR code printed on the constancia (a siat.sat.gob.mx validadorqr URL), or an array with both. The first-page QR returns the taxpayer; the seal QR returns the issue date.","items":{"type":"string"},"type":["string","array"]}},"required":["qr"],"title":"QR code","type":"object"},{"properties":{"file":{"contentEncoding":"base64","description":"The constancia as base64: the PDF SAT generated, or a PNG or JPEG image of it. A `data:` URL prefix is accepted. Up to 8 MB.","type":"string"}},"required":["file"],"title":"File","type":"object"}]}},"multipart/form-data":{"schema":{"properties":{"file":{"contentMediaType":"application/pdf","description":"The constancia file: the PDF SAT generated, or a PNG or JPEG image of it. Up to 8 MB.","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"document":{"description":"The constancia that was sent. Null unless a file or a seal QR was sent.","properties":{"age_days":{"description":"Days from `issued_at` to today in Mexico City.","type":["integer","null"]},"alert":{"description":"The verdict on the file. `edited`: SAT did not issue a constancia with this seal, or the file differs in `rfc`, `id_cif`, `issued_at`, `curp`, or `start_date`, which cannot change after issue. Reject it. `outdated_or_edited`: it differs only in data a taxpayer can change (address, regimes, status, name); ask for a new constancia, and treat a recent one (`age_days`) as suspicious. null: nothing differs, or there was nothing to compare.","examples":["edited","outdated_or_edited"],"type":["string","null"]},"data":{"anyOf":[{"$ref":"#/components/schemas/CsfTaxpayer"},{"type":"null"}],"description":"What the file prints. Null for an image or a scanned PDF."},"differences":{"description":"Fields that do not agree: `rfc`, `id_cif`, `issued_at`, `name`, `curp`, `start_date`, `status`, `status_date`, `address.*`, `regimes`. The taxpayer changed that data after the constancia was issued, or the file was edited.","example":["address.zip"],"items":{"type":"string"},"type":"array"},"issuance":{"description":"`verified`: SAT confirms it issued a constancia with this seal. `rejected`: SAT says it did not, or the seal belongs to another taxpayer. `not_verifiable`: the constancia predates SAT's online seal check, or the file has no seal QR. null: SAT could not be asked about the seal.","examples":["verified","rejected","not_verifiable"],"type":["string","null"]},"issued_at":{"description":"When the constancia was issued, Mexico City time, no zone. SAT's own record when `issuance` is `verified`; otherwise what the constancia states. Older constancias carry the date alone.","example":"2026-10-16T08:45:15","type":["string","null"]},"issued_in":{"description":"Place of issue the constancia prints.","example":"CUAUHTEMOC, CIUDAD DE MEXICO","type":["string","null"]},"matches_sat":{"description":"Whether `data` agrees with SAT's current record. Null when there is no `data` or no `taxpayer` to compare.","type":["boolean","null"]}},"type":["object","null"]},"found":{"description":"true = SAT has a constancia for that idCIF and RFC, with its current record in `taxpayer` (for a seal QR alone: SAT issued that constancia); false = SAT answered that it has none (charged); null = SAT unreachable (not charged).","type":["boolean","null"]},"id_cif":{"description":"idCIF asked about. Null when only a seal QR was sent.","type":["string","null"]},"message":{"description":"Plain-language summary. For `found: false` it is SAT's own message, in Spanish.","type":"string"},"rfc":{"description":"RFC asked about.","type":"string"},"taxpayer":{"anyOf":[{"$ref":"#/components/schemas/CsfTaxpayer"},{"type":"null"}],"description":"The taxpayer as SAT has it today."}},"type":"object"}}},"description":"Check completed. `found` is true / false / null."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to `invalid_fields` and `fields` listing every missing, mixed, or malformed field. A file that is not a PDF or image, or carries no constancia QR code, lists `file`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Read and verify a Constancia de Situación Fiscal"}},"/curp/lookup":{"post":{"description":"Returns the identity RENAPO has registered for a CURP. The CURP is checked offline first; one that fails is rejected with `invalid_curp` without a RENAPO call and is not charged. A CURP RENAPO has no record of (`found: false`) costs 5 credits. ~2 s.","externalDocs":{"description":"Endpoint guide","url":"https://curpcheck.com/docs/endpoints/curp-lookup"},"operationId":"curpLookup","requestBody":{"content":{"application/json":{"schema":{"properties":{"curp":{"description":"The CURP (18 characters, any case)","example":"TU_CURP_REAL","type":"string"},"include_pdf":{"default":false,"description":"Include the official PDF as pdf_base64 at no extra credit cost.","type":"boolean"}},"required":["curp"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"summary":"Abbreviated illustrative response; identifiers and names are placeholders.","value":{"curp":"TU_CURP_REAL","found":true,"message":"Identity retrieved from RENAPO","person":{"associated_curps":[],"certification":"CURP Certificada: verificada con el Registro Civil","certified":true,"curp":"TU_CURP_REAL","homonimo":false,"mothers_maiden_name":"APELLIDO MATERNO","names":"NOMBRES","paternal_surname":"APELLIDO PATERNO","renapo_valid":true}}}},"schema":{"properties":{"curp":{"type":"string"},"found":{"description":"true = RENAPO returned the record in `person`; false = RENAPO did not return a single record (charged; `person.homonimo` is true when RENAPO reports a problem with the key); null = RENAPO unreachable (not charged).","type":["boolean","null"]},"message":{"type":"string"},"pdf_base64":{"contentEncoding":"base64","contentMediaType":"application/pdf","description":"Official RENAPO PDF; present only when include_pdf is true and found is true.","type":"string"},"person":{"anyOf":[{"$ref":"#/components/schemas/CurpIdentity"},{"type":"null"}]}},"type":"object"}}},"description":"Search completed. `found` is true / false / null."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to: `missing_curp` or `invalid_curp`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Look up a CURP in RENAPO"}},"/curp/search":{"post":{"description":"Searches RENAPO by name, birth date, sex, and state of birth (the \"Datos personales\" form on gob.mx) and returns the CURP registered for that person. Names are uppercased and stripped of accents (Ñ and Ü stay). Every invalid field is reported at once in a 422. ~2 s.","externalDocs":{"description":"Endpoint guide","url":"https://curpcheck.com/docs/endpoints/curp-search"},"operationId":"curpSearch","requestBody":{"content":{"application/json":{"schema":{"properties":{"birthdate":{"example":"1980-01-01","format":"date","type":"string"},"include_pdf":{"default":false,"description":"Include the official CURP PDF in pdf_base64 at no extra credit cost. A PDF download failure returns found: null and is not charged.","type":"boolean"},"mothers_maiden_name":{"description":"Omit when the person has a single surname.","example":"MARTINEZ","type":"string"},"names":{"example":"JUAN","type":"string"},"paternal_surname":{"example":"PEREZ","type":"string"},"sex":{"enum":["H","M","X"],"type":"string"},"state":{"description":"Two-letter state of birth code as used in CURPs (e.g. DF, JC, NL), or NE for people born abroad.","example":"DF","type":"string"}},"required":["names","paternal_surname","birthdate","sex","state"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"summary":"Abbreviated illustrative response; identifiers and names are placeholders.","value":{"curp":"TU_CURP_REAL","found":true,"message":"Identity retrieved from RENAPO","person":{"associated_curps":[],"certification":"CURP Certificada: verificada con el Registro Civil","certified":true,"curp":"TU_CURP_REAL","homonimo":false,"mothers_maiden_name":"APELLIDO MATERNO","names":"NOMBRES","paternal_surname":"APELLIDO PATERNO","renapo_valid":true}}}},"schema":{"properties":{"curp":{"type":"string"},"found":{"description":"true = RENAPO returned the record in `person`; false = RENAPO did not return a single record (charged; `person.homonimo` is true when RENAPO reports a problem with the key); null = RENAPO unreachable (not charged).","type":["boolean","null"]},"message":{"type":"string"},"pdf_base64":{"contentEncoding":"base64","contentMediaType":"application/pdf","description":"Official RENAPO PDF; present only when include_pdf is true and found is true.","type":"string"},"person":{"anyOf":[{"$ref":"#/components/schemas/CurpIdentity"},{"type":"null"}]}},"type":"object"}}},"description":"Search completed. `found` is true / false / null."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to `invalid_fields` and `fields` listing every missing or malformed field."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Find a CURP by personal data"}},"/geo/zip":{"post":{"description":"Returns the state, municipality, city, and settlements (colonias) of a zip code, from our copy of the Catálogo Nacional de Códigos Postales that Correos de México (SEPOMEX) publishes, refreshed daily. ~ms. Free under any active plan; 1 credit for pay-as-you-go callers.","externalDocs":{"description":"Endpoint guide","url":"https://mexcheck.com/docs/endpoints/geo-zip"},"operationId":"geoZip","requestBody":{"content":{"application/json":{"schema":{"properties":{"zip":{"description":"The five-digit zip code, as a string so a leading zero is kept.","example":"22000","pattern":"^\\d{5}$","type":"string"}},"required":["zip"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"city":{"description":"The city, when the zip code is in one.","example":"Tijuana","type":["string","null"]},"found":{"type":"boolean"},"message":{"type":"string"},"municipality":{"description":"The municipality, or the alcaldía in Mexico City.","example":"Tijuana","type":["string","null"]},"municipality_code":{"description":"Three-digit INEGI municipality code within the state.","example":"004","type":["string","null"]},"settlements":{"description":"Every settlement the zip code serves, by name.","items":{"properties":{"name":{"example":"Zona Centro","type":"string"},"type":{"description":"Colonia, Fraccionamiento, Ejido, Pueblo, Ranchería...","example":"Colonia","type":["string","null"]},"zone":{"description":"Urbano, Semiurbano, or Rural.","example":"Urbano","type":["string","null"]}},"type":"object"},"type":"array"},"state":{"description":"The state as Correos de México names it.","example":"Baja California","type":["string","null"]},"state_code":{"description":"Two-digit INEGI state code.","example":"02","type":["string","null"]},"zip":{"example":"22000","type":"string"}},"type":"object"}}},"description":"Lookup completed. `found` is false, with the place fields null and `settlements` empty, when the catalogue has no such zip code."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to `invalid_fields` and `fields` to `[\"zip\"]`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`geo_unavailable`: the catalogue is being loaded. Not charged."}},"security":[{"apiKey":[]}],"summary":"Look up what a Mexican zip code covers"}},"/geo/zip-search":{"post":{"description":"Searches Correos de México's zip code catalogue by state, municipality, settlement (colonia) name, or the first digits of the zip code. Send at least one of `zip`, `municipality`, or `settlement`. Names match whatever their accents and capitals. ~ms. Free under any active plan; 1 credit for pay-as-you-go callers.","externalDocs":{"description":"Endpoint guide","url":"https://mexcheck.com/docs/endpoints/geo-zip-search"},"operationId":"geoZipSearch","requestBody":{"content":{"application/json":{"schema":{"properties":{"limit":{"default":50,"description":"How many results to return.","maximum":200,"minimum":1,"type":"integer"},"municipality":{"description":"Letters found anywhere in the municipality's name.","example":"San Nicolás de los Garza","minLength":3,"type":"string"},"settlement":{"description":"Letters found anywhere in the settlement's name.","example":"Miraflores","minLength":3,"type":"string"},"state":{"description":"The state's name or how it starts (`Veracruz`). `Estado de México` and `CDMX` are understood. Narrows a search; cannot be sent alone.","example":"Nuevo León","type":"string"},"zip":{"description":"The first two to five digits of the zip code.","example":"664","pattern":"^\\d{2,5}$","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"count":{"description":"How many results this response carries.","type":"integer"},"results":{"description":"Matching settlements, by zip code and then name.","items":{"properties":{"municipality":{"example":"San Nicolás de los Garza","type":"string"},"settlement":{"example":"Miraflores","type":"string"},"state":{"example":"Nuevo León","type":"string"},"type":{"example":"Colonia","type":["string","null"]},"zip":{"example":"66410","type":"string"},"zone":{"example":"Urbano","type":["string","null"]}},"type":"object"},"type":"array"},"truncated":{"description":"True when more settlements matched than `limit`.","type":"boolean"}},"type":"object"}}},"description":"Search completed. `results` is empty when nothing matched."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to `invalid_fields` and `fields` to the ones at fault."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`geo_unavailable`: the catalogue is being loaded. Not charged."}},"security":[{"apiKey":[]}],"summary":"Find the zip codes of a place in Mexico"}},"/ine/verify":{"post":{"description":"Asks INE's Lista Nominal service whether a credencial para votar is current. Send `cic` and exactly one of `id_ciudadano` (models E to J) or `ocr` (model D). Values shorter than the full length are left-padded with zeroes. An answer without a record (`found: false`) costs 10 credits; `found: null` means INE could not be reached and is not charged. 4–15 s.","externalDocs":{"description":"Endpoint guide","url":"https://inecheck.com/docs/endpoints/ine-verify"},"operationId":"ineVerify","requestBody":{"content":{"application/json":{"example":{"cic":"123456789","id_ciudadano":"987654321"},"schema":{"properties":{"cic":{"description":"Credential identification code: the nine digits after IDMEX on the first line on the back.","example":"123456789","pattern":"^[0-9]{1,9}$","type":"string"},"id_ciudadano":{"description":"Citizen identifier, models E to J: the last nine digits of the first line on the back. Send this or `ocr`.","example":"987654321","pattern":"^[0-9]{1,9}$","type":"string"},"ocr":{"description":"OCR, model D. Send this or `id_ciudadano`.","example":"1234567890123","pattern":"^[0-9]{1,13}$","type":"string"}},"required":["cic"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"cic":{"type":"string"},"credential":{"anyOf":[{"$ref":"#/components/schemas/IneCredential"},{"type":"null"}]},"found":{"description":"true = INE returned the record in `credential`; false = INE answered without a record (charged); null = INE unreachable (not charged).","type":["boolean","null"]},"message":{"type":"string"},"status":{"description":"INE's verdict. `unknown` means INE returned a record without stating whether it is current.","enum":["vigente","no_vigente","no_encontrada","unknown",null],"type":["string","null"]}},"type":"object"}}},"description":"Lookup completed. `found` is true / false / null."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to `invalid_fields` and `fields` listing every missing or malformed field."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Verify a voter ID with INE"}},"/rfc/find-zip":{"post":{"description":"Searches SAT's massive consultation endpoint to find the postal code registered for an RFC + name combination. Skips the certificate lookup, so the caller must provide the cleaned name (see Names section in the API description). 7–9 s. Webhook supported.\n\nUse this when an invoicing flow needs the zip code but the customer name is already on file.","externalDocs":{"description":"Endpoint guide","url":"https://rfccheck.com/docs/endpoints/find-zip"},"operationId":"rfcFindZip","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"Registered taxpayer name as it appears in SAT. **Companies:** omit legal-entity suffixes (S.A. de C.V., SAPI de C.V., SOFOM, AC, SC, etc.). **Persons:** legal name with no honorifics. See top-level `Names` section.","example":"ACME CONSULTORES","type":"string"},"rfc":{"description":"The RFC number to validate (12 or 13 characters)","example":"XAXX010101000","type":"string"},"webhook_url":{"description":"URL to receive the result asynchronously. The API returns 202 immediately and POSTs the JSON result here when complete. Must be http or https. Redirects are not followed. Max 2048 chars.","example":"https://example.com/webhooks/rfc","format":"uri","maxLength":2048,"type":"string"}},"required":["rfc","name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"generic":{"description":"true for SAT's generic RFCs (XAXX010101000, XEXX010101000, EXTF900101NI1, EXT990101NI1), which identify no taxpayer and are answered without querying SAT.","type":"boolean"},"message":{"type":"string"},"rfc":{"type":"string"},"valid":{"description":"true = zip found; false = combination not in SAT registry; null = SAT unreachable for some batches.","type":["boolean","null"]},"zip":{"type":["string","null"]}},"type":"object"}}},"description":"Search completed (sync mode only). `valid` is true / false / null."},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAccepted"}}},"description":"Accepted: async processing started. Result will be POSTed to the webhook URL."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to one of: `missing_rfc`, `invalid_rfc`, `missing_name`, `invalid_webhook_url`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Find the SAT-registered zip for a known RFC + name"}},"/rfc/profile":{"post":{"description":"Returns the SAT-registered personal data for an RFC:\n\n- **Persona física (individual):** legal name, CURP, and contact email on file.\n- **Persona moral (company):** company name, legal representative RFC + CURP, and contact email on file.\n\nThe data is parsed from the digital certificates (CSD + FIEL) SAT publishes for the RFC. You also get serial, status, and validity dates for each certificate, plus the base64 .cer blob. Sync only, 1–3 s. Use for KYC, account onboarding, or pre-filling customer records.","externalDocs":{"description":"Endpoint guide","url":"https://rfccheck.com/docs/endpoints/profile"},"operationId":"rfcProfile","requestBody":{"content":{"application/json":{"schema":{"properties":{"rfc":{"description":"The RFC number to validate (12 or 13 characters)","example":"XAXX010101000","type":"string"}},"required":["rfc"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"certs":{"items":{"$ref":"#/components/schemas/Certificate"},"type":"array"},"curp":{"description":"CURP of the taxpayer. Only present for persona física.","type":"string"},"email":{"description":"Contact email SAT has on file for the taxpayer.","type":"string"},"found":{"description":"true = SAT returned a registered taxpayer; false = SAT has no record; null = SAT unreachable.","type":["boolean","null"]},"generic":{"description":"true for SAT's generic RFCs (XAXX010101000, XEXX010101000, EXTF900101NI1, EXT990101NI1), which identify no taxpayer and are answered without querying SAT.","type":"boolean"},"legal_representative_curp":{"description":"CURP of the legal representative. Only present for persona moral.","type":"string"},"legal_representative_rfc":{"description":"RFC of the legal representative. Only present for persona moral.","type":"string"},"message":{"type":"string"},"name":{"type":["string","null"]},"rfc":{"type":"string"},"source":{"description":"sat_registry confirms registration only; it provides no certificate profile or identity details. Omitted for generic RFCs.","enum":["sat_certificates","sat_registry"],"type":"string"}},"type":"object"}}},"description":"Lookup completed. `found` is true / false / null. Missing or unavailable certificates fall back to SAT registry verification: `source` is `sat_registry`, `name` is null and `certs` is empty. An answered fallback costs 1 credit; a full certificate profile costs 3 credits. An unavailable answer costs no credits."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to: `missing_rfc` or `invalid_rfc`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Look up the registered taxpayer's personal data"}},"/rfc/sat-lists":{"post":{"description":"Returns 69-B / 69 / 69-B bis listings for an RFC. Local DB lookup, no SAT roundtrip. ~ms. Use for compliance dashboards.","externalDocs":{"description":"Endpoint guide","url":"https://rfccheck.com/docs/endpoints/sat-lists"},"operationId":"rfcSatLists","requestBody":{"content":{"application/json":{"schema":{"properties":{"rfc":{"description":"The RFC number to validate (12 or 13 characters)","example":"XAXX010101000","type":"string"}},"required":["rfc"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"rfc":{"type":"string"},"sat_lists":{"items":{"$ref":"#/components/schemas/SatListing"},"type":"array"}},"type":"object"}}},"description":"Lookup completed. `sat_lists` is empty when the RFC is in no list."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to: `missing_rfc` or `invalid_rfc`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"List SAT-published contributor lists an RFC appears in"}},"/rfc/validate":{"post":{"description":"Runs the full validation pipeline: certificate lookup for the registered name, zip-code search, certificate enrichment, and SAT-list lookup. The response includes registration status, taxpayer name, postal code, digital certificates, and SAT-list presence. RENAPO identity lookup is disabled by default. Set `include_curp: true` to enable it for 5 additional credits (15 total, $0.225 USD pay-as-you-go).\n\n**Identity enrichment:**\n- **Company / persona moral:** includes `legal_representative` with the representative's verified name, surnames, birthdate, CURP status, and other identity details.\n- **Individual / persona física:** includes `person` only when a CURP is available in the source data; not every individual response includes it.\n- Identity details are verified through RENAPO. If that government lookup is unavailable, RFC validation still completes without the corresponding identity object.\n\nWebhook delivery is supported.\n\n**Latency:**\n- Without `name`: 7–11 s (cert lookup + zip search run sequentially).\n- **With `name`** (recommended when you know it): 6–10 s. Cert lookup and zip search run in parallel, and you also recover a zip for registered RFCs that have zero CSDs.\n- When enabled, identity lookup runs alongside zip discovery and is capped at 45 s.\n\nWhen the provided `name` doesn't match SAT records, the response is `valid: false` with a message explaining the registered name. Use the more targeted endpoints (`/profile`, `/find-zip`, `/verify`) when you already have part of the answer.","externalDocs":{"description":"Endpoint guide","url":"https://rfccheck.com/docs/endpoints/validate"},"operationId":"validateRfc","requestBody":{"content":{"application/json":{"schema":{"properties":{"include_curp":{"default":false,"description":"Enable RENAPO identity lookup for the taxpayer or legal representative when a CURP is available. Adds 5 credits to the request (15 total, $0.225 USD pay-as-you-go).","type":"boolean"},"name":{"description":"Optional. When provided, cert lookup and zip search run in parallel (6–10 s instead of 7–11 s) and a zip is recovered even when the RFC has zero CSDs. Registered taxpayer name as it appears in SAT. **Companies:** omit legal-entity suffixes (S.A. de C.V., SAPI de C.V., SOFOM, AC, SC, etc.). **Persons:** legal name with no honorifics. See top-level `Names` section.","example":"ACME CONSULTORES","type":"string"},"rfc":{"description":"The RFC number to validate (12 or 13 characters)","example":"XAXX010101000","type":"string"},"webhook_url":{"description":"URL to receive the result asynchronously. The API returns 202 immediately and POSTs the JSON result here when complete. Must be http or https. Redirects are not followed. Max 2048 chars.","example":"https://example.com/webhooks/rfc","format":"uri","maxLength":2048,"type":"string"}},"required":["rfc"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"certs":{"items":{"$ref":"#/components/schemas/Certificate"},"type":"array"},"curp":{"description":"CURP of the taxpayer. Only present for persona física.","type":"string"},"email":{"description":"Contact email SAT has on file for the taxpayer.","type":"string"},"generic":{"description":"true for SAT's generic RFCs (XAXX010101000, XEXX010101000, EXTF900101NI1, EXT990101NI1), which identify no taxpayer and are answered without querying SAT.","type":"boolean"},"legal_representative":{"$ref":"#/components/schemas/LegalRepresentative","description":"Verified identity for a persona moral's legal representative, including name, surnames, birthdate, and CURP status. Present only with `include_curp: true`, an available CURP, and a successful RENAPO lookup."},"legal_representative_curp":{"description":"CURP of the legal representative. Only present for persona moral.","type":"string"},"legal_representative_rfc":{"description":"RFC of the legal representative. Only present for persona moral.","type":"string"},"message":{"type":"string"},"name":{"type":["string","null"]},"person":{"$ref":"#/components/schemas/CurpIdentity","description":"Verified identity for a persona física taxpayer. Present only with `include_curp: true`, an available CURP, and a successful RENAPO lookup."},"rfc":{"type":"string"},"sat_lists":{"items":{"$ref":"#/components/schemas/SatListing"},"type":"array"},"valid":{"description":"true = registered, false = not registered, null = SAT unreachable (retry later)","type":["boolean","null"]},"zip":{"type":["string","null"]}},"type":"object"}}},"description":"Successful validation. `valid` is true / false / null (null = SAT unreachable)."},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAccepted"}}},"description":"Accepted: async processing started. Result will be POSTed to the webhook URL."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized: invalid or missing API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required: insufficient balance or no active subscription"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to one of: `missing_rfc`, `invalid_rfc`, `invalid_webhook_url`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests: rate limit exceeded"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Full RFC validation (cert lookup + zip search + lists)"}},"/rfc/verify":{"post":{"description":"Two modes:\n\n- **RFC only** (`{rfc}`): quick padrón check via SAT's ValidaRFC endpoint. 1–2 s. Confirms whether the RFC is registered and active with SAT.\n- **Full combo** (`{rfc, name, zip}`): single-round-trip combo check via the massive-consultation endpoint. 1–2 s. Confirms that the RFC + name + zip combination matches SAT's records.\n\nProvide `name` and `zip` together (combo mode), or neither (RFC-only mode). Providing only one is rejected with 422.","externalDocs":{"description":"Endpoint guide","url":"https://rfccheck.com/docs/endpoints/verify"},"operationId":"rfcVerify","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"Optional. Requires `zip`. Registered taxpayer name as it appears in SAT. **Companies:** omit legal-entity suffixes (S.A. de C.V., SAPI de C.V., SOFOM, AC, SC, etc.). **Persons:** legal name with no honorifics. See top-level `Names` section.","example":"ACME CONSULTORES","type":"string"},"rfc":{"description":"The RFC number to validate (12 or 13 characters)","example":"XAXX010101000","type":"string"},"zip":{"description":"Optional. Requires `name`. 5-digit Mexican postal code","example":"06600","pattern":"^\\d{5}$","type":"string"}},"required":["rfc"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"generic":{"description":"true for SAT's generic RFCs (XAXX010101000, XEXX010101000, EXTF900101NI1, EXT990101NI1), which identify no taxpayer and are answered without querying SAT.","type":"boolean"},"message":{"type":"string"},"rfc":{"type":"string"},"valid":{"description":"true = SAT confirms; false = SAT rejects; null = SAT unreachable.","type":["boolean","null"]}},"type":"object"}}},"description":"Verification completed."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to one of: `missing_rfc`, `invalid_rfc`, `missing_name` (zip provided without name), `missing_zip` (name provided without zip), `invalid_zip`."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gateway Timeout: the lookup did not finish within 90 seconds. Body is `{\"error\": \"request_timeout\"}`. Not charged."}},"security":[{"apiKey":[]}],"summary":"Verify an RFC, optionally against a name + zip"}},"/rfc/verify-batch":{"post":{"description":"Submits up to 5000 records to SAT in a single round-trip and returns per-record verdicts. 10–15 s for the whole batch, so the per-record cost is tiny when amortized. **Webhook required**: there is no sync mode for this endpoint.","externalDocs":{"description":"Endpoint guide","url":"https://rfccheck.com/docs/endpoints/verify-batch"},"operationId":"rfcVerifyBatch","requestBody":{"content":{"application/json":{"schema":{"properties":{"records":{"items":{"properties":{"name":{"description":"Registered taxpayer name as it appears in SAT. **Companies:** omit legal-entity suffixes (S.A. de C.V., SAPI de C.V., SOFOM, AC, SC, etc.). **Persons:** legal name with no honorifics. See top-level `Names` section.","example":"ACME CONSULTORES","type":"string"},"rfc":{"description":"The RFC number to validate (12 or 13 characters)","example":"XAXX010101000","type":"string"},"zip":{"description":"5-digit Mexican postal code","example":"06600","pattern":"^\\d{5}$","type":"string"}},"required":["rfc","name","zip"],"type":"object"},"maxItems":5000,"type":"array"},"webhook_url":{"description":"URL to receive the result asynchronously. The API returns 202 immediately and POSTs the JSON result here when complete. Must be http or https. Redirects are not followed. Max 2048 chars.","example":"https://example.com/webhooks/rfc","format":"uri","maxLength":2048,"type":"string"}},"required":["records","webhook_url"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAccepted"}}},"description":"Accepted: async processing started. Result will be POSTed to the webhook URL."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Body has `error` set to one of: `missing_records`, `missing_webhook_url`, `invalid_webhook_url`, `empty_batch`, `batch_too_large`, `invalid_record` (with `index` and `reason`)."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"security":[{"apiKey":[]}],"summary":"Bulk-verify up to 5000 RFC + name + zip records"}}},"servers":[{"description":"Production server","url":"https://mexcheck.com/v1"}]}