IMSS · NSS lookup

You already have the CURP. We give you the NSS.

Stop asking your user for their Social Security card, which almost nobody can find. You send their CURP and their Social Security Number (NSS) arrives at your system.

Request access → View documentation ›
input: CURP onlyresult to your webhookno NSS is an answer too
consulta-nssAPI EXAMPLES

Pick a scenario and see what your system receives:

Fictional data with the exact structure the API returns. None of it belongs to a real person.

Where it fits

The field that is always missing, without asking anyone for it.

The NSS is eleven digits almost nobody remembers, printed on a card almost nobody can find. Asking for it in a form costs you drop-off; typing it by hand costs errors. The CURP, on the other hand, you already have.

◈
Payroll and social-security registrationRegister the person without asking for extra documents. Less friction in onboarding.
✓
A confirmed number, not a typed oneThe NSS comes from IMSS, not from what someone typed. No more swapped digits or someone else's number.
⊘
Fewer fields to ask forEvery field you remove from your form is one more person who finishes signing up. And one less sensitive value you ask your user for.
Available today

We do not ask you to trust us. Check it.

It is common for the NSS lookup to appear in a catalog or in some documentation and not exist when it is time to integrate. So before talking to us, there are three things you can check on your own.

1
The endpoint is publishedWith its route, its inputs and its cost in credits, in the open API reference. No sign-up.See the endpoint ↗
2
Every response has its exampleEvery case it can return, with the full JSON for each one. Not a general description: the contract.See the examples ↗
3
You test it with your own casesWe enable courtesy credits in production. You send your own CURPs and see what comes back, before signing anything.Request access →
How it works

You send the CURP. The NSS arrives at your system.

You do not keep a request open or your user waiting in front of the screen. You send the query with an address of yours, called a webhook, and we deliver the result there as soon as it is ready.

{ }
You send the CURPwith your webhook address
You get a receiptwith a query ID
✓
The NSS arrivesat your webhook, with the same ID

First time using a webhook? We explain it step by step → · See all IMSS services →

Business cases

When there is no NSS, it tells you.

No response leaves you guessing. The type field names the case with a stable code and your backend decides with a switch.

typeWhat happenedWhat to do
SUCCESSThe person's NSS was found. All 11 digits are included.Proceed. Use it for registration.
PERSON_WITHOUT_NSSThe CURP exists, but has no NSS assigned.Review. It usually means the person was never registered with IMSS.
CURP_NOT_FOUNDIMSS could not find that CURP.Review. Check the CURP against RENAPO.
IMSS_INCONSISTENT_DATAThe CURP exists, but its data is inconsistent at IMSS.Review. The person must clarify it with the institute.
IMSS_OPERATION_LIMITIMSS applied a temporary limit to that query.Retry later.
SERVICE_UNAVAILABLEIMSS is not available.Retry. Not charged.
INVALID_REQUESTThe CURP is malformed or the webhook is missing. Answered immediately, when you create the query.Fix the request. Not charged.
Raw infrastructure · 100% REST API

One call. One input.

You send the CURP and your webhook address. Same envelope as every OrigoID service.

CURP onlyYou do not need the card or any other detail about the person.
2 credits per resolved queryCharged when there is a result. The receipt is free.
Zero retentionThe result is delivered to your webhook and we do not keep it afterwards.
View documentation ↗
consulta-nss 
const res = await fetch("https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ORIGOID_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    curp: "XEXX010101HNEXXXA4",
    webhook: { url: "https://your-domain.com/hooks/origoid" },
  }),
});

const receipt = await res.json(); // type: "ACCEPTED"
import os, requests

res = requests.post(
    "https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async",
    headers={"x-api-key": os.environ["ORIGOID_API_KEY"]},
    json={
        "curp": "XEXX010101HNEXXXA4",
        "webhook": {"url": "https://your-domain.com/hooks/origoid"},
    },
    timeout=30,
)
receipt = res.json()  # type: "ACCEPTED"
curl -X POST https://api.origoid.com/mex/social-security/v1/imss-nss-lookup-async \
  -H "x-api-key: $ORIGOID_API_KEY" \
  -H "content-type: application/json" \
  -d '{"curp": "XEXX010101HNEXXXA4", "webhook": {"url": "https://your-domain.com/hooks/origoid"}}'
Immediate receipt
{
  "status": "OK",
  "type": "ACCEPTED",
  "transactionId": "39b972d3-20a8-539a-acfb-70657588df9b",
  "billable": false
}
What arrives at your webhook
{
  "status": "OK",
  "type": "SUCCESS",
  "message": "NSS found",
  "data": { "nss": "00000000000" },
  "transactionId": "39b972d3-20a8-539a-acfb-70657588df9b",
  "billable": true
}
Want to know whether that person works today?

For employment verification the CURP is also enough: you get the employer, the base salary and the contributed days of the period.

See employment verification →
Has your team never used a webhook?

We prepared a guide that explains it without jargon: what it is, what your system needs to receive the result and how to get it working.

See the webhooks guide →
Why OrigoID

A small field that unblocks a whole process.

The NSS is rarely the goal: it is the requirement that holds up a registration. What matters is getting it without stopping your user and knowing clearly what happened when it does not exist.

◈
Without stopping your userThe user carries on with sign-up while the result arrives at your system.
⚑
Never a silenceIf there is no NSS assigned, if the CURP is not found or if the data is inconsistent, the response names it with a stable code.
⊘
Zero retentionYour user's NSS is delivered to your webhook and we do not keep it afterwards.
$
Published pricing2 credits per query, and the price per credit drops with your volume. All public. See pricing

OrigoID is not IMSS and does not act on its behalf: it is a technical means of querying and cross-checking against that source. The accuracy and currency of the information depend on the institute itself.

Frequently asked

What people usually ask us.

Can you get the NSS from the CURP alone?

Yes. You send the CURP and receive the 11-digit Social Security Number. You do not need the card or any other detail about the person.

How do I receive the result?

At your webhook. When you create the query you get a receipt with an ID; when the result is ready we send it to your address with that same ID.

What if the person has no NSS?

The response says so with PERSON_WITHOUT_NSS: the CURP exists but has no NSS assigned, which usually means the person was never registered with IMSS. That is useful information, not an error.

What do customers use it for?

Mostly to register people for payroll or social security without asking for extra documents, and to confirm an NSS the user typed.

How much does it cost?

2 credits per resolved query. The receipt is not charged. Plans are published.

Do you store the query data?

No. The result is delivered to your webhook and we do not keep it afterwards. Zero retention across all our regions.

Try it with your own cases.

Courtesy credits to query in production. Access is enabled after a brief validation of your company.

Request access