RFC validation API
The RFC service allows you to validate a Registro Federal de Contribuyentes (RFC) by providing the Constancia de Situación Fiscal (CSF). The process involves sending the CSF file to the service for validation. The service verifies that the document meets all the requirements of a document issued by the SAT (Servicio de Administración Tributaria), thereby confirming the tax identity of an individual or a company.
Use cases
- Digital onboarding: Automatically retrieves official data found in the CFE source during customer registration, without manual uploads.
- KYC compliance: Collects and stores official identity data with authenticity guaranteed from the CFE source.
- Financial services onboarding: Confirms that the address exists and that the service is registered under the name of the person who provided the proof for validation.
- Fraudulent document detection: The service identifies characteristics of fraudulent documents and detects data that do not match the official source, helping to prevent potential fraud attempts.
Base URL
https://web-prod01.tuidentidad.com
Authentication
Each company is assigned a unique, non-transferable API key that must be included to authenticate requests.
Headers
| Tag | Type | Required | Description |
|---|---|---|---|
| ApiKey | string | yes | Customer key. |
Example: ApiKey: YOUR_API_KEY
Rate Limit RFC using CSF
20QPM
avg=7.48s
min=4.92s
med=6.91s
max p(90)=15.38s/10.67s
p(95)=11.36s
Endpoint
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/rfc | Validate RFC using a CSF document. |
Validate RFC using CSF Document
Validates an RFC by processing a Constancia de Situación Fiscal (CSF) document.
The service extracts information from the document and validates the RFC.
POST /api/rfc
Request
Headers
| Header | Type | Required | Description | Default value |
|---|---|---|---|---|
| ApiKey | string | yes | API authentication key | — |
Query parameters
| Field | Type | Required | Description | Default value |
|---|---|---|---|---|
| v | string | yes | API version | 1 |
Body Parameters
| field | Type | Required | Validations | Description | Regex | Example |
|---|---|---|---|---|---|---|
| file | string($binary) | yes | image/png, image/jpeg, application/pdf, image/jpg weight < 5 MB | CSF document file (JPG, PDF or PNG). to be analyzed with OCR. | — | file=@"file.pdf";type=application/pdf |
Examples of Successfull Request
CURL - PDF
curl --request POST \
--url "https://web-prod01.tuidentidad.com/RFC?v=1" \
--header 'apikey: TU_API_KEY_AQUI' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@constancia_situacion_fiscal.pdf;type=application/pdf'
CURL PNG image
curl --request POST \
--url "https://web-prod01.tuidentidad.com/RFC?v=1" \
--header 'apikey: TU_API_KEY_AQUI' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@constancia_situacion_fiscal.png;type=image/png'
Successful Response
{
"valid": boolean,
"data": {
"personType": "string",
"rfc": "string",
"rfcDic":"string",
"rfcBarcode":"string",
"businessName": "string",
"name": "string",
"lastName": "string",
"secondLastName": "string",
"registerStatus": "string",
"emailContact": "string",
"startDate": "string",
"capitalRegime": "string",
"fiscalRegime": "string",
"fiscalRegimeDate": "string",
"legalAddress": {
"street": "string",
"externalNumber": "string",
"internalNumber": "string",
"road": "string",
"zipCode": "string",
"suburb": "string",
"municipality": "string",
"state": "string"
}
},
"warnings": [
{
"code": "string",
"message": "string",
"fullMessage": "string"
}
]
}
Examples of Bad Request
Request
curl --request POST \
--url "https://web-prod01.tuidentidad.com/RFC?v=1" \
--header 'apikey: TU_API_KEY_AQUI' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@documento.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document'
Response (400 - Bad request)
{
"statuscode": 400,
"code": "RFCS002",
"message": "Invalid file format.",
"fullMessage": ""
}
Example of request with error - SAT unavailable
{
"statuscode": 503,
"code": "RFCS009",
"message": "Unable to validate the document with the source.",
"fullMessage": ""
}
Response fields
| Field | Type | Description |
|---|---|---|
| valid | boolean | Indicates whether the RFC validation was successful |
| data | object | Extracted and validated RFC information |
| warnings | array | List of warnings or non-critical issues |
| code | string | Error code. |
| message | string | Error message. |
| fullMessage | string | Complete message of the error code. |
Data object
| Field | Type | Description |
|---|---|---|
| personType | string | Person type could be 1=physical person, 2=juridical person. |
| rfc | string | Registro Federal de Contribuyentes. |
| businessName | string | Legal name of the company. |
| name | string | Name. |
| lastName | string | Lastname. |
| secondLastName | string | Second lastname. |
| registerStatus | string | Status. Example: "ACTIVO". |
| emailContact | string | E-mail that was registered for contact. |
| startDate | string | Start date. |
| capitalRegime | string | Capital regime. |
| fiscalRegime | string | Fiscal regime. |
| fiscalRegimeDate | string | Fiscal regime Date |
| legalAddress | object | Extracted and validated address information |
| street | string | Public road in a city, town, or village, typically with buildings |
| externalNumber | string | # Ext |
| internalNumber | string | # Int |
| road | string | Wide way or route that connects different places, allowing vehicles, people |
| zipCode | string | ZIP code |
| suburb | string | Residential area located on the outskirts of a city, where people live outside the busy urban center, often in quieter neighborhoods. |
| municipality | string | Administrative division or local government unit that has its own governing authority, typically responsible for managing a city, town, or district. |
| state | string | Large political and administrative division within a country, with its own government that handles regional laws and public services. |
Examples Bad Request
400 Bad Request - Invalid File format
{
"statuscode": 400,
"code": "RFCS002",
"message": "Invalid file format.",
"fullMessage": ""
}
401 Unauthorized — Invalid API key
{
"statuscode": 401,
"code": "RFCS010",
"message": "Invalid API key.",
"fullMessage": ""
}
415 Unsupported Media Type — The file exceeds the allow weight.
{
"statuscode": 415,
"code": "RFCS006",
"message": "File size exceeds the allowed limit.",
"fullMessage": ""
}
500 Internal Server Error - Fail of OCR.
{
"statuscode": 500,
"code": "RFCS005",
"message": "OCR processing failed.",
"fullMessage": ""
}
503 Service Unavailable - The SAT is out of service.
{
"statuscode": 503,
"code": "RFCS009",
"message": "Unable to validate the document with the source.",
"fullMessage": ""
}
HTTP Status Codes
The API uses standard HTTP status codes to indicate the success or failure of a request.
| Code | Status | Description |
|---|---|---|
| 200 | OK | The request was successfully processed. The response may include warnings. |
| 202 | Accepted | The request has been accepted for processing but is not yet complete (asynchronous flow). |
| 204 | No Content | The request was successful but no content is returned. |
| 400 | Bad Request | The request is invalid or missing required parameters. |
| 413 | Payload Too Large | The uploaded file exceeds the maximum allowed size. |
| 415 | Unsupported Media Type | The file format is not supported. |
| 422 | Unprocessable Entity | The document could not be processed or parsed correctly. |
| 500 | Internal Server Error | An unexpected error occurred on the server. |
| 503 | Service Unavailable | An internal service or external dependency is temporarily unavailable. |
| 504 | Gateway Timeout | The request to an external service timed out. |
Error response format
| Field | Type | Description |
|---|---|---|
| code | string | Error code identifier |
| message | string | Message |
| fullMessage | string | Large description of the error. |
json
{
"valid": false,
"warnings": [
{
"code": "string",
"message": "string",
"fullMessage": "string"
}
]
}
Error codes
Warnings codes
| Code | Message | Description | HTTP status code | Category |
|---|---|---|---|---|
| RFCS001 | Failed to retrieve data. | The service was unable to retrieve the requested data. | 500 | Technical |
| RFCS002 | The image file format is not correct. | The uploaded file is not a valid CSF document or the file format is not supported (.png, .jpg, .pdf). | 415 | Client |
| RFCS004 | The {field} field is required. | The request contains required fields that are empty or contain only blank spaces. | 400 | Client |
| RFCS005 | OCR failed. | The OCR process failed while scanning the document. | 502 | Technical |
| RFCS006 | File Size is larger than expected. | The uploaded file exceeds the maximum allowed size of 5 MB. | 413 | Client |
| RFCS007 | Inconsistent data found. | The OCR process detected inconsistent or incorrect information in the document. | 400 | Client |
| RFCS008 | The document cannot be read. | The document could not be processed by the OCR engine. | 502 | Dependency |
| RFCS009 | Unable to validate the document with the source. | The service could not validate the document against the SAT database. | 503 | Dependency |
| RFCS010 | The apiKey is not valid | The provided API key is invalid. | 401 | Client |
| RFCS011 | Response time has exceeded | The server took too long to respond and the request timed out. | 504 | Technical |
| RFCS012 | Failed to retrieve server response. | An error occurred while retrieving the response from the server. | 500 | Technical |
| RFCS013 | RFC or BusinessName does not match the source. | The provided RFC does not match the company information registered in the SAT. | 203 | Dependency |
| RFCS014 | No certificates found for the RFC. | The RFC does not have any certificates available for validation. | 203 | Dependency |
| RFCS015 | The structure is not correct. | The provided RFC does not have a valid format. | 400 | Client |
| RFCS017 | No matches found in SAT. | The RFC was not found in the SAT database. | 200 | Dependency |
| RFCS018 | Legal address is incomplete or does not match OCR. | The extracted legal address is incomplete or does not match the OCR results. | 200 | Technical |
| RFCS019 | RFC information not found. | No information associated with the RFC could be retrieved from SAT. | 200 | Dependency |
| RFCS020 | Fiscal regime information cannot be verified. | The fiscalRegime and fiscalRegimeDate fields could not be verified against SAT records. | 422 | Dependency |
| RFCS021 | RFC values do not match in OCR results. | The RFC, RFCBarcode, and RFCDic values extracted during OCR processing do not match. | 422 | Technical |
| RFCS022 | Invalid CSF document detected. | The classification model determined that the uploaded file is not a valid CSF document. | 400 | Client |
| RFCS024 | Image classification error. | An error occurred while processing the file in the image classification model. | 500 | Technical |
| #### Error Categories |
Client: Error in the API consumer request (invalid data, incorrect format, credentials).
Dependency: Failure in external services or providers (SAT, Canica).
Technical: Failure in TuIdentidad's internal infrastructure or code.
File requirements
When uploading a CSF document:
| Requirement | Value |
|---|---|
| Formats | (PNG, JPG) or PDF |
| Maximum size | 5 MB |
| Image quality | Image with good focus, without modifications, without blemishes, without folds, without light flares, without excess margin or background in the capture. |
Support
If you encounter issues integrating the API, contact the Tu Identidad support team.