CURP + IMSS Validation API
Overview
This service allows clients to validate a CURP and retrieve associated NSS (Social Security Number) information through a unified request.
Description
The API integrates two validation processes into a single endpoint. When a CURP is submitted, the service:
- Sends a synchronous request to RENAPO to validate and retrieve CURP data.
- Initiates an asynchronous request to IMSS to obtain the NSS associated with the CURP.
The CURP data is returned immediately in the response. For the NSS data, the response includes a verificationId
that the client must use to perform a follow-up request to retrieve the NSS result once it becomes available or receive a webhook notification with the NSS response data.
Endpoint
POST /api/ImssCurp/validate
Request
Headers
Header | Type | Required | Description |
---|---|---|---|
apiKey | string | Yes | Client's API key. |
Body Parameters
Parameter | Type | Required | Max Length | Description |
---|---|---|---|---|
CURP | string | Yes | 18 | Clave Única de Registro de Población (CURP). |
Response
{
"valid": true,
"curpData": {
"valid": true,
"curp": "string",
"names": "string",
"lastName": "string",
"secondLastName": "string",
"dateBirth": "string",
"sex": "string",
"federalEntity": "string",
"curpStatus": "string"
},
"nssData": {
"verificationId": "12345-ABC-678"
},
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
valid
: Indicates if the overall validation was successful.curpData
: Contains the details from the CURP validation.valid
: Indicates if the CURP is valid.curp
: The CURP consulted.names
: Name(s) of the person.lastName
: Paternal surname.secondLastName
: Maternal surname.dateBirth
: Date of birth.sex
: Sex (H/M).federalEntity
: Federative entity of birth.curpStatus
: Status of the CURP (active, inactive, etc.).
nssData.verificationId
: A unique ID used to retrieve the asynchronous NSS result from IMSS.warnings
: Optional list of non-critical messages or alerts.
Warnings and Error Handling
The service may return warnings and errors to provide feedback on non-critical conditions or issues that prevent successful processing. All messages follow a consistent error model structure.
Warning and Error Model
{
"code": "string",
"message": "string",
}
- code: A short identifier for the warning or error type (e.g.,
CURP_NOT_FOUND
,IMSS_TIMEOUT
). - message: A human-readable description of the issue.
Warnings are included in the warnings
array of the main response body and do not interrupt processing. Errors will result in an unsuccessful response with appropriate HTTP status codes and error content.
Example Warning Response
{
"success": true,
"curpData": { /* valid data */ },
"nssData": { "verificationId": "12345-ABC-678" },
"warnings": [
{
"code": "",
"message": "",
}
]
}
Common Service Messages
Code | Message | Status Code |
---|---|---|
IMCU001 | Internal Server Error | 500 |
IMCU002 | Incorrect response format from a dependency service | 502 |
IMCU003 | Service Unavailable | 503 |
IMCU004 | Gateway Timeout | 504 |
IMCU010 | Failed to deserialize response from a dependency service | 502 |
IMCU005 | Bad Request - Invalid CURP | 400 |
IMCU006 | Unauthorized | 401 |
IMCU009 | API key is missing or invalid | 401 |
IMCU007 | Forbidden | 403 |
IMCU008 | Not Found | 404 |
Dependency Service Errors
In addition to the errors generated directly by this service, it can also relay errors from its internal dependencies (such as the CURP or NSS validation services). When a dependency returns an error, this service will prepend the prefix IC
to the original error code and return it. The error message from the dependency is preserved without modification.
For example, if an internal service returns the following error:
{
"code": "CURP011",
"message": "The CURP field is not in the allowed format."
}
This service will return:
{
"code": "ICCURP011",
"message": "The CURP field is not in the allowed format."
}
Next Step: Retrieve NSS Result
Use the verificationId
to retrieve the NSS result from the NSS by CURP Verification Service.