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.

References