Social Security (Signal3)

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.

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

1. Submit a Social Security Signals request using POST /beta/signals/createSignal3. Provide templateId, consent, and the identity fields required by your chosen template.

2. 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.

3. 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.

Supported ID Types

Social Security Signal Object

This is the object returned in the response.

Item Object

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

Statuses

Result Codes

📘

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.

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.