🗂️ NSS

The NSS (Número de Seguro Social) validation report retrieves and validates Mexico’s Social Security Number from the Instituto Mexicano de Seguro Social (IMSS). This report is essential for employment verification and social security compliance in Mexico.

Overview

NSS validation provides access to Mexico’s social security system to verify employment history, contribution status, and eligibility for social benefits. This report is crucial for employment verification and compliance with Mexican labor laws.

Input Requirements

Required Fields

Field	Type	Description	Example
`document_id`	string	CURP (Clave Única de Registro de Población)	`ABCD123456EFGHIJ78`

Optional Fields

Field	Type	Description	Default
`full_name`	string	Expected full name for verification	Auto from CURP
`report_settings`	object	Configuration options	`{}`

Data Source

Registry: Instituto Mexicano de Seguro Social (IMSS) Authority: Secretaría del Trabajo y Previsión Social Coverage: All Mexican workers with formal employment Update Frequency: Real-time for active workers, monthly for historical data

Output Schema

Active NSS Found

{
  "nss": {
    "state": "COMPLETED",
    "created_at": "2021-03-30T03:18:33.921896",
    "updated_at": "2021-03-30T03:19:46.417538",
    "outcome": "PASSED",
    "details": {
      "curp": "ABCD123456EFGHIJ78",
      "full_name": "JUAN MIGUEL DOE ROE",
      "nss": "12345678901",
      "status": "ACTIVE",
      "registration_date": "2015-03-15",
      "last_contribution": "2024-01-15",
      "employer_info": {
        "current_employer": "EMPRESA EJEMPLO SA DE CV",
        "employer_registration": "A1234567890",
        "employment_start": "2020-06-01",
        "salary_range": "CONFIDENTIAL"
      },
      "contribution_history": {
        "total_weeks": 156,
        "continuous_weeks": 78,
        "last_12_months": 52
      },
      "validation": {
        "nss_format_valid": true,
        "check_digit_valid": true,
        "active_in_system": true
      }
    }
  }
}

Inactive NSS

{
  "nss": {
    "state": "COMPLETED",
    "created_at": "2021-03-30T03:18:33.921896",
    "updated_at": "2021-03-30T03:19:46.417538",
    "outcome": "PASSED",
    "details": {
      "curp": "ABCD123456EFGHIJ78",
      "full_name": "JUAN MIGUEL DOE ROE",
      "nss": "12345678901",
      "status": "INACTIVE",
      "registration_date": "2010-05-20",
      "last_contribution": "2019-12-31",
      "employer_info": {
        "last_employer": "EMPRESA ANTERIOR SA",
        "employment_end": "2019-12-31",
        "termination_reason": "VOLUNTARY"
      },
      "contribution_history": {
        "total_weeks": 312,
        "continuous_weeks": 0,
        "last_12_months": 0
      },
      "validation": {
        "nss_format_valid": true,
        "check_digit_valid": true,
        "active_in_system": false
      }
    }
  }
}

No NSS Found

{
  "nss": {
    "state": "COMPLETED",
    "created_at": "2021-03-30T03:18:33.921896",
    "updated_at": "2021-03-30T03:19:46.417538",
    "outcome": "FAILED",
    "details": {
      "curp": "ABCD123456EFGHIJ78",
      "full_name": "JUAN MIGUEL DOE ROE",
      "nss": null,
      "status": "NOT_FOUND",
      "message": "No NSS registration found for provided CURP",
      "possible_reasons": [
        "Person never worked in formal employment",
        "Only worked in informal economy",
        "Recent graduate without employment history",
        "Self-employed without IMSS registration"
      ]
    }
  }
}

NSS Format and Validation

NSS Structure

The NSS is an 11-digit number with the following format:

12345678901

Format Breakdown

Position	Digits	Description	Example
1-2	Numbers	Subdelegation code	`12`
3-4	Numbers	Year of registration	`34`
5-10	Numbers	Sequential number	`567890`
11	Number	Check digit	`1`

Check Digit Algorithm

function validateNSSCheckDigit(nss) {
  if (nss.length !== 11) return false;

  const digits = nss.split('').map(Number);
  const checkDigit = digits[10];

  // IMSS check digit algorithm
  let sum = 0;
  for (let i = 0; i < 10; i++) {
    sum += digits[i] * (i + 1);
  }

  const calculatedCheckDigit = sum % 11;
  const finalCheckDigit = calculatedCheckDigit === 10 ? 0 : calculatedCheckDigit;

  return checkDigit === finalCheckDigit;
}

Business Logic and Usage

When to Use NSS Validation

Employment Verification: Confirm formal employment history
Social Security Compliance: Verify IMSS contributions
Payroll Validation: Ensure proper social security registration
Benefits Eligibility: Check qualification for social benefits
Labor Law Compliance: Meet Mexican employment regulations

Employment Status Interpretation

Active Status

Current Employment: Person is actively employed
Recent Contributions: Contributions within last 3 months
Benefits Eligible: Qualified for IMSS benefits
Formal Economy: Working in registered employment

Inactive Status

No Current Employment: Not currently contributing
Historical Record: Previous employment history available
Benefits Status: May retain some benefits based on contribution history
Transition Period: May be between jobs or in informal work

Not Found Status

No Formal Employment: Never registered with IMSS
Informal Economy: May work in unregistered employment
Recent Graduate: May not have employment history yet
Self-Employed: May not be required to register with IMSS

Configuration Options

Basic Configuration

{
  "report_settings": {
    "nss": {
      "include_employer_details": true,
      "include_contribution_history": true
    }
  }
}

Advanced Configuration

{
  "report_settings": {
    "nss": {
      "include_employer_details": true,
      "include_contribution_history": true,
      "include_salary_information": false,
      "historical_depth_months": 24,
      "verify_employment_dates": true
    }
  }
}

Configuration Parameters

Parameter	Type	Description	Default	Options
`include_employer_details`	boolean	Include current/last employer information	`true`	true/false
`include_contribution_history`	boolean	Include contribution statistics	`true`	true/false
`include_salary_information`	boolean	Include salary range data	`false`	true/false
`historical_depth_months`	integer	Months of history to retrieve	`12`	1-60
`verify_employment_dates`	boolean	Cross-verify employment dates	`false`	true/false

Error Handling

Common Issues

Error Type	Description	Resolution
`INVALID_CURP`	CURP format invalid or not found	Verify CURP with RENAPO first
`IMSS_TIMEOUT`	IMSS database timeout	Retry after 15-30 minutes
`ACCESS_RESTRICTED`	Limited access to detailed information	Contact support for enhanced access
`DATA_PRIVACY_RESTRICTION`	Salary information restricted	Remove salary settings from configuration
`SYSTEM_MAINTENANCE`	IMSS system under maintenance	Check IMSS service status

Best Practices

CURP Validation First: Always validate CURP before NSS lookup
Privacy Compliance: Handle employment data according to Mexican privacy laws
Data Retention: Follow data retention policies for employment information
Error Handling: Implement proper retry logic for system timeouts

API Integration

Create Person with NSS Check

curl -X POST "https://api.emptor.io/v3/mx/persons" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "ABCD123456EFGHIJ78",
    "city_locode": "MX MEX",
    "pipeline": {
      "name": "standard_id_check"
    },
    "report_settings": {
      "nss": {
        "include_employer_details": true,
        "include_contribution_history": true,
        "historical_depth_months": 12
      }
    }
  }'

Get NSS Report Details

curl -X GET "https://api.emptor.io/v3/mx/details/{person_id}/nss" \
  -H "X-Api-Key: YOUR_API_KEY"

Legal and Compliance Considerations

Mexican Labor Law

Ley Federal del Trabajo: Employment verification requirements
Ley del Seguro Social: IMSS registration obligations
Data Protection: LFPDPPP compliance for employment data
Worker Rights: Respect for employee privacy and data rights

Employment Verification Use Cases

Pre-Employment Screening

Verify claimed employment history
Confirm social security compliance
Assess employment stability
Validate formal economy participation

Payroll Compliance

Ensure proper IMSS registration
Verify contribution status
Confirm employer obligations
Monitor compliance requirements

Benefits Administration

Determine benefit eligibility
Calculate contribution periods
Verify employment continuity
Assess qualification criteria

Create Person - Initiate NSS validation
Get Reports - Retrieve NSS results
Get Report Details - Detailed NSS data
Update Reports - Refresh NSS validation

CURP Validation - Mexico ID validation
RFC Validation - Mexico tax ID validation
Pipeline Selection Guide - Choosing verification strategies
Legal Glossary - Legal terminology