@singula_systems/identity-js integration guide

Your API key (sk_live_*) never reaches the browser: the server creates the session and only the short-lived token travels to the front-end. The widget accepts it with or without the vt_ prefix. Camera permissions are granted to Singula’s origin, not yours. And the verdict of record lives server-side: onComplete is UX, not authorization.

It is the same session: send the link over WhatsApp to someone who is not on your site and open the widget for someone who is. A raw <iframe> with embed_url and no library loads too, but then the init handshake is on you; without it the page closes with origin_unknown.

When the pipeline could not produce a verdict there is nothing to assert about the person, so the session goes to a human instead of claiming a rejection.

No identity route accepts the API key as a URL parameter, the event stream included: a key in a URL leaks through logs and referrers.

The list governs framing. verification_url opens as its own tab (email, SMS, WhatsApp) and has no parent to authorize. In all three failures above, the capture never starts.

If the customer already had a pending verification, THAT one is returned with reused: true: nothing is charged again and its options are NOT changed. To start over, cancel the previous one with POST …/customer/{customerId}/cancel (cancelling is free).

With an INE, a passport or a resident card and a customer that has a CURP, the session checks the document’s CURP, name, date of birth and sex against RENAPO at no extra charge: it reuses the CURP validation that already exists for that CURP and, when there is none, runs one internally when the verification is submitted, without charging it (it shows up in your activity with bundled_with). A CURP validation you ask for — POST /app/curp/validate or a CURP step in a flow — is charged. The INE is also checked against the Lista Nominal: it arrives after the verdict, on the same request_id, with the identity.listanominal.completed webhook. The same rule holds over the API, the dashboard, the SDK, links and flows.

A third-party <script> is code you delegate to a CDN. Pin the exact version and let the browser verify the bytes with integrity (see the panel): a mis-served object then fails closed instead of running. The hash covers ONE file, so it is useless with a moving alias or across versions.

Stages and verdict are independent: five passed stages imply no decision, and with the verdict withheld the decision stage never arrives at all. Drive your UI from onComplete, and read the verdict on your server.

Never grant anything on the strength of a browser callback: it describes what the page in front of that person says happened, and whoever holds the keyboard can call your handler with anything. Use requestId to ask YOUR backend, which holds the API key.

The verdict lands minutes after the submit, over a channel that can die (the tab gets throttled, the session is cancelled). The SDK arms a backstop as soon as it sees the submit: if nothing arrives within verdictTimeoutMs (35 min) it fires verdict_timeout once. retryStage() is reserved: the hosted page does not act on it today.

With wrong_document the photo shows ANOTHER ID: detected_document_type says which one. The hosted page puts it this way — "This photo looks like your resident card" / "Here we need the back of your INE" — with "Take it again" and, only when the session also offers the detected document, "Use my resident card": it switches documents and opens that capture from its first side, keeps the liveness check (it is never repeated) and, once its last side is taken, goes straight to the submit. On the new document's first side, "Back" undoes the switch. When the page does not recognize the document, it says "This photo looks like another document" and only offers to take it again. With your own screens, switching documents means confirming the new one's photos and naming it on submit: since MasterApi 1.130.0 submit accepts { "document_type": "resident_card" } (ine, passport or resident_card), which wins over the inference — without it, the session verifies the document of the LAST document photo confirmed, and a slow confirm of the abandoned document may arrive later —. It has to be one the session offers, with its photos; a photo of a document the session does not offer answers 400 document_type_not_offered.

Up to three photos of each side are checked (max_attempts). On the third, retake_suggested comes back false even if the photo is still poor: start the verification, and a fourth photo comes back unavailable. Never repeat the liveness check: only the photo that was asked for. The verdict decides as always: a document that could not be read comes back failed (review), a check digit that fails on a poor-quality photo comes back partial (review) with the retake_suggested check, and whatever is rejected today is still rejected.

Confirming the SAME photo again neither counts as a new photo nor checks it again. The route authenticates with the token, like presign and confirm: 404 when it does not exist, 409 once the session was sent, 410 when it expired; 300 reads per minute per session and 3000 per IP (since MasterApi 1.130.0), and it never returns S3 keys. The other capture routes have their own per-minute ceilings: presign, confirm and the multipart upload, 600 per session and 3000 per IP; submit, 60 and 600. Past a ceiling they answer 429 with Retry-After, the seconds to wait before retrying. Neither the check nor the retaken photos are charged: the verification is charged as always, once, with its verdict. In sandbox it answers ok with nothing checked, and the deprecated multipart upload has no pre-check.

With @singula_systems/identity-js 0.7.0 or later, onRetake({ side, reason, attempt }) fires every time the page asks for another photo: side is front or back (the passport data page is front), reason is one of the nine codes above and attempt is 1 on the first retake of that side and 2 on the second. Since 0.8.0, wrong_document also carries detectedDocumentType: ine, passport or resident_card (lower case; detected_document_type in the message), absent when the page did not recognize the document. A 0.7.0 SDK receives wrong_document as unreadable, and with 0.7.0 or earlier a capture with a resident card stops sending onStepChange (it drops the document it does not know): upgrade to 0.8.0. It travels as the document_retake message. It is informative only — the page already asks for the photo itself — and an older SDK ignores it.

Apart from the pre-check, the final result may carry the retake_suggested check, false: an MRZ check digit failed on a poor-quality photo, so the session landed on partial (review) instead of rejected, or the bottom zone on the back of an INE could not be read, so the session landed on partial instead of verified. It is informative, does not count towards the score and its details says what to do: ask for another photo. See the hard rule in How the score is computed.

The raw verification object is kept unchanged: anyone already reading from it changes nothing. 404 when that requestId is not yours.

network carries the session’s trusted IPs — the one our server saw, never a client X-Forwarded-For — with country, ASN and whether they are Tor, cloud/hosting/VPN or iCloud Private Relay. It is a signal: it charges nothing and never rides the webhook. The IP of whoever uploads the photos counts too: if your backend uploads them from a cloud with POST /app/identity-verification/submit/:token, that IP is hosting and, in a KYC dossier, ip_not_hosting sends it to review (never to a decline). Upload them from the person’s device — the hosted link or the widget — or switch kyc.checks.ip_not_hosting off (and ip_country_vs_document if your server is outside Mexico) in the verification policy. Country and ASN come from an open IP geolocation database. If you show them on your screens, include the data credits listed at singula.mx/en/credits.

A category with no checks in that verification does not count as zero: its weight is split proportionally across the ones that are present, so a missing signal does not drag the score down. The usual case is RENAPO: on an INE with no RENAPO record (the customer has no CURP, or RENAPO did not confirm it) the weights become 66.7% critical, 20% internal consistency and 13.3% quality (each divided by 0.75). A passport and a resident card are scored with the same rule over their own checks: the printed data and the CURP against their MRZ count as internal consistency, and with a customer that has a CURP they carry the RENAPO category too.

If liveness, the face match or an MRZ check digit fails, the verdict is rejected (decision: declined) whatever the score. It is checked before the bands: the score is still computed and returned, but it cannot rescue a rejection. A score of 0.87 with a failed liveness check is still a rejection. On a passport the check digits of its number, the date of birth, the expiry and the composite count as critical; the optional personal number’s does not. An expired passport or an impossible date of birth is never verified: at most partial (decision: review), even with a score above 0.85. And one whose MRZ could not be read comes back failed. On a resident card the check digits of the document number, the date of birth, its MRZ expiry field and the composite are critical. A card that has expired, has an impossible date of birth or was not issued by Mexico is never verified, and neither is a temporary one whose printed expiry could not be read (or does not fall between its issue date and four years later), one whose MRZ is not an INM card’s, nor one whose front does not carry the MRZ name or whose printed issue date is not the MRZ’s: another person’s front; a permanent one does not expire. With no readable MRZ, it comes back failed. One exception, on the INE, the passport and the resident card: a check digit that fails on a poor-quality photo — with no failed face match or liveness — does not reject: the session comes back partial (decision: review) with the retake_suggested check, because on that photo the digit may simply have been misread. On a good photo it is still a rejection. And an INE whose bottom zone on the back (the MRZ) could not be read is never verified: at most partial (decision: review), also with retake_suggested.

They are audit evidence and up to 30 extra signatures, so they are not signed by default. Ask for them with include_frames=true when you are actually going to review them.

end { reason: "timeout" } is THAT stream’s 15-minute cap with the session still open: reconnect, or read status/{requestId}. Only terminal closes the story. A verification is completed by a person: it takes as long as it takes.

X-Singula-Signature arrives as t=<unix>,v1=<hmac>, where the HMAC-SHA256 is computed over `${t}.${rawBody}` with your webhook secret. Compute it on the RAW body, before parsing. The event also rides in X-Singula-Event.

With a webhook registered in the dashboard you get the { id, type, created, data } envelope, signed and retried: read body.data. On the fallback route (no registered webhook) the same object arrives flat and unsigned. Sandbox sends exactly the same payload, so what you integrate against tests works in production.

The gate is browser-only. status and result with an API key and the identity.completed webhook keep delivering the full verdict whether you expose it or not. Handle withheld from day one: it is what a freshly configured organization emits.

A page that remounts after the submit does not render "link already used": the verdict is missing, so it keeps reading the status and shows "we received your verification". The dead-link screen is only for completed, cancelled and expired.

Overrides travel twice: as URL params, for the first paint, and over the init message once the iframe is ready, which is the authoritative channel. A rejected option throws without leaving anything mounted.

Three layers, each overriding only the fields it carries: your ORGANIZATION’s branding (Settings › Branding) is the base; a FLOW may bring its own in settings.ui, frozen into the published version; and theme, on the call, wins over both and applies to that session only. With no theme, the session looks like the flow — or like the organization, when the flow fixed no appearance. The object is sent the same way for an identity verification and for a flow: it is the same Identity.open.

The capture is public (the token is the auth), so the environment is not decided there: it is inherited from the key that created the verification. From the dashboard its mode fixes it: in «Sandbox» it sends X-Singula-Env: sandbox and the verification is born a test one, free, as with sk_test_. Same response shape as production, so what you integrate in testing does not change when you go live.

The sandbox’s identity, INE, CURP against RENAPO and verified email all describe the same sample person: MARIA LOPEZ GARCIA, CURP LOGM900101MDFPRR02, born 1990-01-01. The sanction lists and the judicial search do answer with the name actually searched — your customer’s — and return it in queries. That is deliberate: a test KYC dossier that crossed two different people could never approve.