The Social Security API retrieves a subject's current social security contribution record directly from the IMSS (Instituto Mexicano del Seguro Social), Mexico's national social security authority. A successful response contains the subject's verified employer information, contribution base amount, number of contribution days, and the state where contributions are being made — sourced directly from official IMSS records.

Because the data is retrieved from a live government system, Social Security requests are asynchronous. The API creates a record immediately and returns a PROCESSING status. When the record is ready — typically within one minute — you are notified via webhook, after which you can retrieve the completed record by ID.

Social Security is currently in Alpha.

Supported Market

Template ID	Market	Required Parameters
`tpl-sss003001`	Mexico (MX)	`mobileNumber`, `fullName`, `curp`, `emailAddress`

📘
Mobile Number Privacy
MD5-encrypted mobile number input is accepted. Submit the encrypted value as MD5(countryCode + mobileNumber) — for example, MD5(529559991234) for a Mexican number. This allows you to pass the identifier without transmitting the raw phone number in plaintext.

How a Social Security Request Works

Submit a Social Security request using POST /alpha/socialSecurities. Provide templateId, consent, mobileNumber, fullName, curp, and emailAddress.
Receive an initial PROCESSING response. The API returns a Social Security object with status: PROCESSING and result: null. The actual retrieval from IMSS is now in progress.
Wait for the webhook. When the record transitions to COMPLETED or ERROR, Smile sends a Records Completed webhook event containing the record ID.
Retrieve the completed record. Use GET /alpha/socialSecurities/{id} to fetch the final record. When status is COMPLETED and resultCode is SUCCESS, the result object contains the subject's social security data.

The Social Security Objects

Request Object

Attribute	Type	Required	Description
templateId	string	Yes	The template to use. Currently `tpl-sss003001` for Mexico.
consent	object	Yes	Evidence of the subject's consent. See Consent Templates for details.
mobileNumber	string	Yes	The subject's mobile number including country code, no leading zeros. Example: `529559991234`. MD5-encrypted input is also accepted (see note above).
fullName	string	Yes	The subject's full name as registered with IMSS.
curp	string	Yes	The subject's CURP (Clave Única de Registro de Población), Mexico's unique population registry code. Example: `DOEJ800101HDFXXX01`.
emailAddress	string	Yes	The subject's email address.

Social Security Object

This is the object returned in both the initial POST response and the subsequent GET response.

Attribute	Type	Description
id	string	Unique ID of this Social Security record. IDs use the prefix `ss-`.
createdAt	date-time	Date and time when this record was created
status	string	Current processing status. See Statuses below.
resultCode	string	Final result of the retrieval. `null` while `status` is `PROCESSING`. See Result Codes below.
resultMessage	string	Human-readable description of the result. `null` while `status` is `PROCESSING`.
result	object	The social security data retrieved from IMSS. `null` until `status` is `COMPLETED`. See Result Object below.
requestMeta	object	Echo of the original request parameters sent with the check

Result Object

The result field is populated once status reaches COMPLETED and resultCode is SUCCESS.

Attribute	Type	Description
fullName	string	The subject's full name as recorded by IMSS
curp	string	The subject's CURP
nss	string	The subject's NSS (Número de Seguro Social), Mexico's social security number
reportDate	date	The date the IMSS report was generated, in `YYYY-MM-DD` format
employerName	string	Name of the subject's current employer as registered with IMSS
employerRegistration	string	The employer's IMSS registration number
state	string	The Mexican state where contributions are being made
contributionDays	integer	Number of days of social security contributions recorded for the subject
contributionBaseAmount	number	The base salary amount used to calculate contributions
currency	string	Currency of the `contributionBaseAmount`. Always `MXN`.

Statuses

Status	Description
`PROCESSING`	The record is being retrieved from IMSS. `result` is `null`. Wait for the webhook before polling.
`COMPLETED`	The retrieval completed. Inspect `resultCode` and `result` for the outcome.
`ERROR`	The retrieval could not be completed. Check `resultMessage` for details.

Result Codes

Result Code	Description	Billable
`SUCCESS`	The IMSS record was retrieved successfully. The `result` object contains the subject's data.	Yes
`NO_DATA`	No IMSS record was found for the provided identifiers.	No
`INVALID_PARAMETERS`	One or more request parameters were invalid (e.g. malformed CURP). Check the request and retry.	No
`SYSTEM_ERROR`	An internal error occurred. Contact Smile support if this persists.	No
`SERVICE_UNAVAILABLE`	The IMSS data source is temporarily unavailable.	No

Webhooks

When a Social Security record transitions to COMPLETED or ERROR, Smile sends a Records Completed webhook event. Subscribe to this event to avoid polling — your endpoint will be called with the record ID, which you can use to fetch the final result.

See Webhooks for setup instructions and the full list of event types.

Sample Social Security data

Initial response (PROCESSING)

{
  "id": "ss-17bbf36498de4d68a0d4f86c7b62f69f",
  "createdAt": "2021-04-14T09:30:24Z",
  "status": "PROCESSING",
  "resultCode": null,
  "resultMessage": null,
  "result": null,
  "requestMeta": {
    "templateId": "tpl-sss003001",
    "mobileNumber": "529559991234",
    "fullName": "John Doe",
    "curp": "DOEJ800101HDFXXX01",
    "emailAddress": "john.doe@example.com",
    "consent": {
      "type": "Terms And Conditions",
      "version": "1.0.0",
      "consentedWith": "I agree to the terms and conditions.",
      "consentedAt": "2021-04-14T09:30:24Z",
      "consentTemplateId": "ct-5b79399a68524234bb0ead472648282d"
    }
  }
}

Completed response

{
  "id": "ss-17bbf36498de4d68a0d4f86c7b62f69f",
  "createdAt": "2021-04-14T09:30:24Z",
  "status": "COMPLETED",
  "resultCode": "SUCCESS",
  "resultMessage": "Success!",
  "result": {
    "fullName": "John Doe",
    "curp": "DOEJ800101HDFXXX01",
    "nss": "12345678901",
    "reportDate": "2024-01-15",
    "employerName": "ABC Corporation",
    "employerRegistration": "ABC123456",
    "state": "SINALOA",
    "contributionDays": 365,
    "contributionBaseAmount": 50000,
    "currency": "MXN"
  },
  "requestMeta": {
    "templateId": "tpl-sss003001",
    "mobileNumber": "529559991234",
    "fullName": "John Doe",
    "curp": "DOEJ800101HDFXXX01",
    "emailAddress": "john.doe@example.com",
    "consent": {
      "type": "Terms And Conditions",
      "version": "1.0.0",
      "consentedWith": "I agree to the terms and conditions.",
      "consentedAt": "2021-04-14T09:30:24Z",
      "consentTemplateId": "ct-5b79399a68524234bb0ead472648282d"
    }
  }
}

Sandbox Testing

Use the following values to trigger a successful response in the Sandbox environment. In Sandbox, records complete immediately without the ~1 minute production delay. Any other valid mobile number will return resultCode: NO_DATA.

Parameter	Value	Expected Response
`templateId`	`tpl-sss003001`
`emailAddress`	Any valid email
`curp`	Any valid CURP
`fullName`	Any string
`mobileNumber`	`529559991234`	`resultCode: SUCCESS`

Endpoints

Endpoint
Create Social Security record	`POST /alpha/socialSecurities`
List Social Security records	`GET /alpha/socialSecurities`
Retrieve one Social Security record	`GET /alpha/socialSecurities/{id}`