This API allows you to obtain the Social Security Number (NSS) using a CURP.
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"
}
}