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 have included a query parameter in Sandbox to enable you to query the test cases that we created for running tests. To get a response, fill the testCaseId parameter with any of the following cases:

Num	Id	Name	Description
1	663567bb713cf2110a1106bd	No encontrado por CURP	Indicates that no information was found for the CURP provided
2	663567bb713cf2110a1106be	No existe la CURP proporcionada	Indicates that the given CURP does not exist.
3	663567bb713cf2110a1106bf	Número de Intentos permitidos	Indicates that the maximum number of queries allowed was exceeded
4	663567bb713cf2110a1106bc	Respuesta exitosa	Indicates one successful response
5	663567bb713cf2110a1106c0	Validar en subdelegación	Indicates that there is a problem with the person consulted and should go to the nearest IMSS subdelegation to resolve the problem.
6	663567bb713cf2110a1106c1	Servicio no disponible	Indicates that the service is not available

📘
Test your own test case
In case you want to test your own test case created in link, you can send in the testCaseId parameter the identifier of the test case you want to use.
For more information visit our knowledge center to know more about test cases

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"
    }
}