Skip to main content
Some IMSS queries take longer than a client should wait on an open HTTP request, so they are offered as asynchronous endpoints. You send the request with a webhook object and we deliver the result to your URL when it is ready.

​
How it works

  1. Create the request. POST the query together with a webhook object. The API answers right away with type: ACCEPTED and a transactionId. Accepting a request is free (billable: false).
  2. Receive the result. When the query resolves, we send an HTTP POST to your webhook.url. The body is the standard envelope, with the same transactionId returned in step 1.
Request:
Immediate response:
If the request is not valid, you get INVALID_REQUEST right away instead of ACCEPTED, and it is never charged:

​
The webhook object

​
Your webhook endpoint

  • It receives an HTTP POST with a JSON body (Content-Type: application/json) and the headers you configured.
  • Answer with any 2xx status as soon as you receive the body, and process it afterwards.
  • Make it idempotent: the same result may be delivered more than once, so use transactionId to de-duplicate.

​
Delivery attempts

We try to deliver each result up to 3 times: right away, then 1 minute and 5 minutes after the previous failed attempt. An attempt fails when your endpoint does not answer with a 2xx status within 10 seconds (redirects are not followed). After the third failed attempt the result is not sent again. Keeping your webhook endpoint available is your responsibility: credits are charged when the result resolves, whether or not your endpoint receives it. For Contribution Weeks you can still fetch the result for 24 hours (see Contribution Weeks fallback).

​
Billing

Credits are charged once, when the result resolves, under the same rule as every other endpoint (see Credits): billable: true when the query was performed — even if the outcome is negative, such as CURP_NOT_FOUND — and false for technical failures. The billable field of the body your webhook receives tells you which applies.

​
Results by service

Each asynchronous endpoint delivers one of the following results to your webhook. Open a type to see its full example.

​
Get NSS (Async)

Same result types as Get NSS, except INVALID_REQUEST, which is returned immediately when you create the request.

​
Employment Status (Async)

Same result types and data as Employment Status, except INVALID_REQUEST, which is returned immediately when you create the request. MISMATCH_CURP_NSS only happens when you send nss, and data.files[] is only included with includePdf: true (the PDF content is shortened in the example).

​
Contribution Weeks

How to read data (SUCCESS and INACTIVE_EMPLOYMENT):
  • Official fields, taken from the IMSS document: nss, personalInfo, contributionWeeks (total = contributed − discounted + reinstated), employmentHistory (one row per job, newest first) and reportDetails (folio, issueDate, digitalSeal, …). files[0] is the official PDF in base64 (shortened in the examples).
  • The active job is the employmentHistory row with endDate: null; in INACTIVE_EMPLOYMENT there is none.
  • Everything computed lives in derivedSignals — currentStatus, jobTenure (months), stability, salary and salaryTimeline. They are facts, not a credit score.
  • Salaries (baseSalary, *Salary) are the daily base contribution salary (SBC); the monthly equivalent is SBC × 30.44. salaryAtLegalCap: true means the salary hit the legal cap (25 UMA), so real income may be higher.
  • Every field is always present; values that do not apply are null.
IMSS_REPORT_UNAVAILABLE and IMSS_RECORD_ERROR are specific to that record while the service is working; they are not charged and the same CURP can be submitted again on a later day.

​
Contribution Weeks fallback

If your webhook could not receive a Contribution Weeks result, fetch it for 24 hours with Contribution Weeks Result (free), sending the transactionId:
It answers RESULT_FOUND (with the original result envelope inside data), RESULT_PENDING or RESULT_EXPIRED. Use it only as a fallback: the result is always sent to your webhook.