Intro

This API allows you to obtain the IMSS NSS by providing the CURP of your client.

Important points

Request

To make the request it is only necessary to provide the Clave Única de Registro de Población, (CURP for its acronym in Spanish), must be an 18-character alphanumeric data.

field	type	required	length	Description
curp	Alphanumeric	Yes	18	Provide a valid CURP according to the CURP rules

If you are not sure how to obtain this field and you have your client's personal data, we suggest you visit our CURP validate by data service to apply a validation and recover the CURP.

Successful response

To know the fields of a successful response you should see our example called success in the response section.

Inside the response object you will only get the next fields.

field Name	Description
nss	11-digit numeric data indicating the recovered NSS
status	Indicates a response status for the query made, the possible values are FOUND, NOT_FOUND, INVALID.
message	A message will be displayed describing the problem why the SSN could not be retrieved

{
    "id": "64f1058b902dd88975d011f4",
    "createdAt": "2023-08-31T15:26:35.872883-06:00",
    "finishedAt": "2023-08-31T15:26:52.443635-06:00",
    "duration": 16570,
    "status": "SUCCESS",
    "request": {
        "curp": "ABCD570805HYNHLC52"
    },
    "response": {
      	"status": "FOUND",
        "nss": "08189782793"
    }
}

📘
Status NOT FOUND
If the response indicates a NOT_FOUND status, it means that the NSS could not be recovered, even though the response has an HTTP code 200. This occurs because we accessed the IMSS system to validate the NSS with the provided data.
For more details we suggest you see the Possible Not Found Responses section.

Test the service (test cases)

We included a query param in Sandbox environment, so you can query test cases that we created to run tests.
In order to obtain the response you shall fill the query param with:

success: it sends back a successful example of a requests.
not_found: it returns the response indicating that a NSS associated with the CURP was not found.
not_found2: it returns the response indicating that the provided CURP was not found in RENAPO and the query could not be applied
attempts_exceeded: it returns a response indicating that the number of daily queries allowed has been exceeded, it occurs when more than two queries were made with the same CURP in one day.
subdelegation_validate: it returns a response indicating that there is an error consulting the NSS and is necessary for the person consulted to go to an IMSS subdelegation to solve the problem in person.
unavailable: it returns a response indicating that the service of the IMSS platform is not available and we could not apply the query.

Listing the possible NOT FOUND responses

Required fields

You will get a 400 bad request error when the CURP is not provided in the request body.

{
    "curp": "REQUIRED_FIELD_ERROR; EMPTY_ERROR; can't be empty"
}

Invalid format

You will get a 400 bad request error when the CURP does not conform the specific format.

{
    "curp": "FORMAT_ERROR; invalid curp format"
}

Test case not found

If a test case parameter is not sent or a value other than those mentioned above is sent, the service will return the following error 400 bad request

{
    "testCase": "EMPTY_ERROR; test case not found",
    "testCaseId": "EMPTY_ERROR; test case not found with given id"
}

NSS not associated to the CURP

There is no NSS associated to the the provided CURP.

{
    "id": "64f0d1278c07811576577e35",
    "createdAt": "2023-08-31T11:43:03.107933-06:00",
    "finishedAt": "0001-01-01T00:00:00Z",
    "duration": 23130,
    "status": "SUCCESS",
    "request": {
        "curp": "NAZA650704MTLVCL05"
    },
    "response" : {
        "status": "NOT_FOUND",
        "message": "No se encontro un numero asociado al CURP"
    }
}

Not existing CURP

The provided CURP does not exist in RENAPO system.

{
    "id": "64f0d1278c07811576577e35",
    "createdAt": "2023-08-31T11:43:03.107933-06:00",
    "finishedAt": "0001-01-01T00:00:00Z",
    "duration": 23130,
    "status": "SUCCESS",
    "request": {
        "curp": "NAZA650704MTLVCL05"
    },
    "response" : {
        "status": "NOT_FOUND",
        "message": "No se localizo informacion en RENAPO con la CURP capturada."
    }
}

Attempts exceeded

The number of attempts (maximum two per day) was exceeded to consult this person

{
    "id": "64f8f50da6e92865602ba748",
    "createdAt": "2023-09-06T15:54:21.418582-06:00",
    "finishedAt": "0001-01-01T00:00:00Z",
    "duration": 0,
    "status": "SERVICE_ERROR",
    "request": {
        "curp": "ABCD570805HYNHLC52"
    },
    "response" : {
        "status": "NOT_FOUND",
        "message": "El número de operaciones por periodo ha sido alcanzada (2 operacion(es) cada 1 dia(s)), favor de intentar más tarde""
    }
}

Subdelegation validate

There is an error when consulting the NSS and the IMSS tells us that the person consulted must go to an IMSS subdelegation to correct their problem.

{
    "id": "64f0d1278c07811576577e35",
    "createdAt": "2023-08-31T11:43:03.107933-06:00",
    "finishedAt": "2023-08-31T11:45:25.327846-06:00",
    "duration": 23130,
    "status": "SUCCESS",
    "request": {
        "curp": "NAZA650704MTLVCL05"
    },
    "response" : {
        "status": "INVALID",
        "message": "Tu solicitud requiere que acudas a la subdelegación."
    }
}

Unavailable service

You will get this error when the IMSS service is not available and we cannot consult the NSS service.

{
    "id": "64f8f610385f8b15cbc07848",
    "createdAt": "2023-09-06T15:58:40.617047-06:00",
    "finishedAt": "0001-01-01T00:00:00Z",
    "duration": 0,
    "status": "SERVICE_ERROR",
    "errorMessage": "Ocurrio un error al intentar obtener la informacion de la pagina, favor de volver a intentar",
    "request": {
        "curp": "ABCD570805HYNHLC52"
    }
}