IMSS - Employment Information Status

Description

Retrieves the status and, once available, the IMSS employment information associated with a request ticket.

Asynchronous Flow

Use the requestId returned by the Request endpoint as the TICKET value. Poll this endpoint while the status is PENDING or PROCESSING.

Step 2 — Retrieve the result

HTTP method GET

Endpoint

https://api.msla-id.com/experience-idv-socialsecurity-api-v1/api/idv-govcheck/v1/mx-identity/imss/{requestId}

[SANDBOX Environment]

For testing purposes, use the base domain: apidev.msla-id.com

Request header parameters

NAME	REQUIRED	TYPE	DESCRIPTION
Authorization	✅	string	Bearer JWT token.
Content-Type	✅	string	application/json.

URI request parameter

NAME	REQUIRED	TYPE	DESCRIPTION
requestId	✅	string	Request identifier returned by the Request endpoint.

Process status

Status	Description
PENDING	Ticket created and awaiting processing.
PROCESSING	Request is being processed.
SUCCESS	Process completed and the report is available.
FAILED	Process failed and no report was generated.

Status code responses

Code	Description
200	Processing status or completed report.
401	Unauthorized
403	Forbidden — IDV-1004
404	Not found — IDV- IMS1002 Ticket not found.
500	Internal server error — IDV-1008
504	Gateway timeout — IDV-1100

Response 200 status code — Success

The response fields (keys) are always in English. queryStatus and contributionStatus.status reflect the raw value returned by the source (IMSS), so they may not be in English — see Possible queryStatus values below.

Employment found and active (queryStatus: VIGENTE):

{
  "traceId": "fd1e96e3f7ec584f",
  "timestamp": "2026-08-24 16:45:57",
  "data": {
    "status": "SUCCESS",
    "message": "La persona tiene informacion IMSS y cuenta con empleo vigente.",
    "socialSecurityNumber": "44190396042",
    "curp": "GOCS031114MMCLRLA0",
    "name": "SOLEDAD GLORIA CIRILO",
    "gender": "MUJER",
    "queryStatus": "VIGENTE",
    "fileNumber": "17873458966511733933813",
    "contributionStatus": {
      "active": true,
      "status": "VIGENTE",
      "criteria": "La constancia oficial reporta semanas cotizadas con empleo activo"
    },
    "contributionSummary": {
      "totalWeeksContributed": 500,
      "weeksContributedImss": 500,
      "weeksDeducted": 0,
      "weeksReinstated": 0,
      "calculationValidated": true,
      "formula": "500 - 0 + 0 = 500"
    },
    "currentEmployment": {
      "companyName": "CORPORATIVO VIAD EXPERTOS EN LIMPIEZA S DE RL DE CV",
      "employerRegistrationNumber": "Y5058324",
      "federalEntity": "CIUDAD DE MEXICO",
      "startDate": "2020-01-01",
      "endDate": null,
      "active": true,
      "dailyBaseSalary": 330.57,
      "currency": "MXN"
    },
    "employmentHistory": [
      {
        "companyName": "CORPORATIVO VIAD EXPERTOS EN LIMPIEZA S DE RL DE CV",
        "employerRegistrationNumber": "Y5058324",
        "federalEntity": "CIUDAD DE MEXICO",
        "startDate": "2020-01-01",
        "endDate": null,
        "active": true,
        "dailyBaseSalary": 330.57,
        "currency": "MXN"
      }
    ]
  }
}

No contribution history found (queryStatus: SIN_HISTORIAL): currentEmployment is null and employmentHistory is an empty array — not null — when the source reports no records.

{
  "traceId": "fd1e96e3f7ec584f",
  "timestamp": "2026-08-24 16:45:57",
  "data": {
    "status": "SUCCESS",
    "message": "La persona es valida, pero no se encontro historial de semanas cotizadas.",
    "socialSecurityNumber": "44190396042",
    "curp": "GOCS031114MMCLRLA0",
    "name": "SOLEDAD GLORIA CIRILO",
    "gender": "MUJER",
    "queryStatus": "SIN_HISTORIAL",
    "fileNumber": "17873458966511733933814",
    "contributionStatus": {
      "active": false,
      "status": "SIN_HISTORIAL",
      "criteria": "La constancia oficial reporta cero semanas cotizadas y no contiene registros laborales"
    },
    "contributionSummary": {
      "totalWeeksContributed": 0,
      "weeksContributedImss": 0,
      "weeksDeducted": 0,
      "weeksReinstated": 0,
      "calculationValidated": true,
      "formula": "0 - 0 + 0 = 0"
    },
    "currentEmployment": null,
    "employmentHistory": []
  }
}

Possible queryStatus values

queryStatus	Meaning
VIGENTE	Person has IMSS information and an active/current employment. currentEmployment is populated.
INACTIVO	Person has IMSS information, but no active employment right now. currentEmployment is null; employmentHistory may still contain past records.
SIN_HISTORIAL	Person is valid, but no contribution-week history was found. currentEmployment is null and employmentHistory is [].
REQUIERE_SUBDELEGACION	The query could not be completed online and requires in-person attention at an IMSS subdelegación. contributionStatus, contributionSummary, currentEmployment and employmentHistory are all null.
REINTENTO_SIGUIENTE_DIA	The query was processed correctly, but IMSS does not allow re-issuing the report for the same CURP on the same day. Retry the next day. Same as above, the detail fields are null.

contributionStatus.status uses the same set of values.

Response 200 status code — Processing

{
  "traceId": "72a998a62bc0f4cd",
  "timestamp": "2026-08-11 08:15:00",
  "data": {
    "status": "PROCESSING",
    "message": "Processing."
  }
}

CURP record not found:

{
    "traceId": "72a998a62bc0f4cd", 
    "timestamp": "2026-03-09 08:15:00",
    "data": {
       "status": "FAILED",
        "message": "Data not found."
    }
}

Service unavailable.:

{
    "traceId": "72a998a62bc0f4cd", 
    "timestamp": "2026-03-09 08:15:00",
    "data": {
        "status": "FAILED",
        "message": "Supplier unavailable."
    }
}

Timed out:

{
    "traceId": "72a998a62bc0f4cd", 
    "timestamp": "2026-03-09 08:15:00",
    "data": {
        "status": "FAILED",
        "message": "Supplier timeout."
    }
}

CURP or NSS validation failed:

{
    "traceId": "72a998a62bc0f4cd",
    "timestamp": "2026-03-09 08:15:00",
    "data": {
        "status": "FAILED",
        "message": "CURP or NSS validation failed."
    }
}

Response 404 status code

{
  "traceId": "c3c48a6057bb0cbc",
  "timestamp": "2026-08-11 11:11:48",
  "code": "IDV- IMS1002",
  "message": "Ticket not found.",
  "data": null
}

Response 500 status code

{
  "traceId": "86c6eda02b615604",
  "timestamp": "2026-08-11 15:44:32",
  "code": "IDV-1008",
  "message": "Error in the source of origin, please contact an administrator!"
}

Note: This error occurs when an unexpected error is generated in the source system. Contact an administrator to review the error.

Response 403 status code

{
  "traceId": "43a20f33d4e8730d",
  "timestamp": "yyyy-mm-dd HH:MM:SS",
  "code": "IDV-1004",
  "message": "Forbidden",
  "data": null
}

Response 504 status code

{
  "traceId": "43a20f33d4e8730d",
  "timestamp": "yyyy-mm-dd HH:MM:SS",
  "code": "IDV-1100",
  "message": "Gateway Timeout",
  "data": null
}