Social Securities (Beta)

The Social Securities 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.

The Beta version adds two improvements over Social Security Alpha: you can now include the subject's NSS (Número de Seguro Social) in the request to improve identity matching accuracy, and the result includes a payMark field indicating whether the most recent contribution has been paid.

Because the data is retrieved from a live government system, Social Securities 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 Securities is currently in Beta.

Supported Market

📘

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 Securities Request Works

1. Submit a Social Securities request using POST /beta/socialSecurities. Provide templateId, consent, mobileNumber, fullName, and curp. Including nss and emailAddress is recommended for higher match accuracy.

2. Receive an initial PROCESSING response. The API returns a Social Securities object with status: PROCESSING and result: null. The actual retrieval from IMSS is now in progress.

3. Wait for the webhook. When the record transitions to COMPLETED or ERROR, Smile sends a Records Completed webhook event containing the record ID.

4. Retrieve the completed record. Use GET /beta/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 including payMark.

The Social Securities Objects

Request Object

Social Securities Object

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

Result Object

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

Statuses

Result Codes

Webhooks

When a Social Securities 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 Securities data

Initial response (PROCESSING)

{
  "id": "ss-17bbf36498de4d68a0d4f86c7b62f69f",
  "createdAt": "2021-04-14T09:30:24Z",
  "status": "PROCESSING",
  "resultCode": null,
  "resultMessage": null,
  "result": null,
  "requestMeta": {
    "templateId": "tpl-sss003002",
    "mobileNumber": "529559991234",
    "fullName": "John Doe",
    "curp": "DOEJ800101HDFXXX01",
    "nss": "12345678901",
    "emailAddress": "[email protected]",
    "consent": {
      "type": "Terms And Conditions",
      "version": "1.0.0",
      "consentedWith": "I agree to the terms and conditions.",
      "consentedAt": "2021-04-14T09:30:24Z",
      "consentTemplateId": null
    }
  }
}

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",
    "payMark": true,
    "reportDate": "2024-01-15",
    "employerName": "ABC Corporation",
    "employerRegistration": "ABC123456",
    "state": "SINALOA",
    "contributionDays": 365,
    "contributionBaseAmount": 50000,
    "currency": "MXN"
  },
  "requestMeta": {
    "templateId": "tpl-sss003002",
    "mobileNumber": "529559991234",
    "fullName": "John Doe",
    "curp": "DOEJ800101HDFXXX01",
    "nss": "12345678901",
    "emailAddress": "[email protected]",
    "consent": {
      "type": "Terms And Conditions",
      "version": "1.0.0",
      "consentedWith": "I agree to the terms and conditions.",
      "consentedAt": "2021-04-14T09:30:24Z",
      "consentTemplateId": null
    }
  }
}

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.

Endpoints