The Social Security Signals API surfaces employment-derived risk signals by querying government social security contribution records for a given subject. Using a combination of identity and phone verification, it returns a set of signals covering income history, employment tenure, contribution continuity, and income stability — all derived directly from official social security data rather than lending activity.

Because the data source is government-held, Social Security Signals requires richer identity verification than phone-only Signals products. Depending on the market, you'll need to provide the subject's full name alongside a government-issued identity number, in addition to their mobile phone number.

Social Security Signals checks are synchronous: results are returned immediately in the API response.

Social Security Signals is currently in Beta.

Available Templates

The template you select determines which identifiers are required and which signals are returned. Each template queries the social security system for a specific market.

Template ID	Market	Required Identifiers
`tpl-sgn003002`	Mexico (MX)	`phone`, `fullName`, `curp`
`tpl-social-securities-signal-th`	Thailand (TH)	`mobileNumber`, `fullName`, `idType`, `idNumber`

All templates also require templateId and consent.

📘
Mobile Number Privacy
MD5-encrypted mobile number input is accepted for both templates. 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 Signals Request Works

Submit a Social Security Signals request using POST /beta/signals/createSignal3. Provide templateId, consent, and the identity fields required by your chosen template.
Receive the result synchronously. The API returns the full Social Security Signal object in the response body. The items array contains the employment signals derived from the subject's social security records.
Evaluate the signals. Each item has a name (the signal identifier), a value, and a valueType. See the data dictionaries for your market for full signal descriptions: Mexico · Thailand.

The Social Security Signals Objects

Request Object

Required fields depend on the template. templateId and consent are always required.

Attribute	Type	Required	Description
templateId	string	Yes	The template to use. Determines the market and required identifiers. See Available Templates above.
consent	object	Yes	Evidence of the subject's consent. See Consent Templates for details.
fullName	string	Yes (all templates)	The subject's full name as registered with their social security authority.
phone	string	Required for `tpl-sgn003002` (MX)	The subject's mobile number including country code, no leading zeros. Example: `529559991234`. MD5-encrypted input is also accepted (see note above).
curp	string	Required for `tpl-sgn003002` (MX)	The subject's CURP (Clave Única de Registro de Población), Mexico's unique population registry code. Example: `DOEJ800101HDFXXX01`.
nss	string	Optional for `tpl-sgn003002` (MX)	The subject's NSS (Número de Seguro Social), Mexico's social security number. When provided, enriches the results with additional contribution-level signals.
emailAddress	string	Optional for `tpl-sgn003002` (MX)	The subject's email address.
mobileNumber	string	Required for `tpl-social-securities-signal-th` (TH)	The subject's mobile number including country code, no leading zeros. Example: `669178912345`. MD5-encrypted input is also accepted (see note above).
idType	string	Required for `tpl-social-securities-signal-th` (TH)	The type of government-issued ID provided. See Supported ID Types below.
idNumber	string	Required for `tpl-social-securities-signal-th` (TH)	The subject's ID number corresponding to the `idType` provided.

Supported ID Types

ID Type	Description	Supported Markets
`PID`	Thai National ID card	TH

Social Security Signal Object

This is the object returned in the response.

Attribute	Type	Description
id	string	Unique ID of this Social Security Signals record. IDs use the prefix `signal-`.
createdAt	date-time	Date and time when this record was created
status	string	Current processing status of the request. See Statuses below.
resultCode	string	Final result code of the check. See Result Codes below.
resultMessage	string	Human-readable description of the result
signalType	string	Always `Signal3` for requests made through this API
requestMeta	object	Echo of the original request parameters sent with the check
items	array	The social security signals returned for this request. See Item Object below.

Item Object

Each entry in the items array represents a single social security signal.

Attribute	Type	Description
name	string	The signal identifier. Example: `event_latest_base_salary`
value	string	The signal value, always returned as a string regardless of the underlying type
valueType	string	The data type of the value. One of: `STRING`, `NUMBER`, `BOOLEAN`

Statuses

Status	Description
`PROCESSING`	The check is currently in progress
`COMPLETED`	The check has completed and results are available
`ERROR`	The check encountered an error and could not be completed

Result Codes

Result Code	Description	Billable
`SUCCESS`	The check completed and social security signal data was returned in the `items` array.	Yes
`NO_DATA`	Smile was unable to return signal data for the provided identifiers.	No
`SYSTEM_ERROR`	An internal error occurred. Contact Smile support if this persists.	No
`SERVICE_UNAVAILABLE`	A required data source is temporarily unavailable.	No

📘
Billing Note
Social Security Signals checks are billed only on SUCCESS. NO_DATA results are not charged. Only the POST /beta/signals/createSignal3 endpoint is counted for billing — List and Get requests are not charged.

About the Items Array

The signals returned in items are derived from the subject's social security contribution history and cover employment income, tenure, stability, and trend data. All signals use NUMBER as the value type unless noted otherwise.

Signal coverage differs by market:

Mexico (tpl-sgn003002) — Signals draw from IMSS (Instituto Mexicano del Seguro Social) records and cover:

Current status — current contribution status flag, most recent base salary, employer name, and the subject's salary rank among peers
Income history — average and maximum salary signals across rolling 3-month, 6-month, 1-year, 3-year, and 5-year windows
Income trends — average monthly income change and income change rate across the same windows
Employment tenure — months worked under the most recent employer, average and maximum tenure across all employers, and total income history length
Income stability — employment rate (proportion of months with income), income volatility (standard deviation), and longest continuous unpaid gap signals across multiple time windows
Employer diversity — number of unique employers across rolling time windows

For the full signal catalog, see the Mexico Data Dictionary.

Thailand (tpl-social-securities-signal-th) — Signals draw from SSO (Social Security Office) records and cover:

Income amounts — most recent income, average, maximum, and rolling-window averages across 6- to 60-month periods
Income trends — average monthly income change across rolling 6- to 60-month windows
Employment history — total months worked, job change count, average and maximum job durations, and income gap statistics
Employer profile — employer company size by employee count and registered capital, and most recent employer type (STRING)

For the full signal catalog, see the Thailand Data Dictionary.

Sample Social Security Signals data

Mexico

{
  "id": "signal-e35d521ef8f147c4aa01b7c1af85aaf7",
  "createdAt": "2021-04-14T09:30:24Z",
  "status": "COMPLETED",
  "resultCode": "SUCCESS",
  "resultMessage": "Success",
  "signalType": "Signal3",
  "requestMeta": {
    "templateId": "tpl-sgn003002",
    "phone": "529559991234",
    "fullName": "John Doe",
    "curp": "DOEJ800101HDFXXX01",
    "nss": "12345678901",
    "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
    }
  },
  "items": [
    {
      "name": "event_latest_base_salary",
      "value": "15000",
      "valueType": "NUMBER"
    },
    {
      "name": "event_latest_employer",
      "value": "Acme Corp SA de CV",
      "valueType": "STRING"
    },
    {
      "name": "event_latest_employer_months_count",
      "value": "24",
      "valueType": "NUMBER"
    },
    {
      "name": "event_salary_current_status_flag",
      "value": "1",
      "valueType": "NUMBER"
    },
    {
      "name": "event_work_months_year1_rate",
      "value": "0.92",
      "valueType": "NUMBER"
    }
  ]
}

Thailand

{
  "id": "signal-f46e632fg9g258d5bb12c8d2bg96bbg8",
  "createdAt": "2021-04-14T09:30:24Z",
  "status": "COMPLETED",
  "resultCode": "SUCCESS",
  "resultMessage": "Success",
  "signalType": "Signal3",
  "requestMeta": {
    "templateId": "tpl-social-securities-signal-th",
    "mobileNumber": "669178912345",
    "fullName": "John Doe",
    "idType": "PID",
    "idNumber": "1234567890123",
    "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
    }
  },
  "items": [
    {
      "name": "event_income_latest",
      "value": "35000",
      "valueType": "NUMBER"
    },
    {
      "name": "event_income_month12_avg",
      "value": "33500",
      "valueType": "NUMBER"
    },
    {
      "name": "event_job_change_count",
      "value": "2",
      "valueType": "NUMBER"
    },
    {
      "name": "event_employer_type_latest",
      "value": "Private",
      "valueType": "STRING"
    },
    {
      "name": "event_work_months_since_first_count",
      "value": "60",
      "valueType": "NUMBER"
    }
  ]
}

Sandbox Testing

Use the following values to trigger a successful response in the Sandbox environment. Any other valid input combination will return resultCode: NO_DATA with an empty items array.

Template ID	Test Input	Expected Response
`tpl-sgn003002` (MX)	`phone: 529559991234`, `fullName: John Doe`, `curp: DOEJ800101HDFXXX01`	`resultCode: SUCCESS`
`tpl-social-securities-signal-th` (TH)	`mobileNumber: 669178912345`, `fullName: John Doe`, `idType: PID`, `idNumber: 1234567890123`	`resultCode: SUCCESS`

Endpoints

📘
Shared List and Get Endpoints
The List and Get endpoints are shared with other Signals products, including Credit Lifecycle and Borrower Screening. When listing, use the signalType=Signal3 query parameter to filter for Social Security Signals records only.

Endpoint
Create Social Security Signals check	`POST /beta/signals/createSignal3`
List Social Security Signals checks	`GET /beta/signals`
Retrieve one Social Security Signals check	`GET /beta/signals/{id}`