Testing Your Integration
How to test your SheerID integration with Test Mode and Live Mode testing — simulate every verification outcome using the test trigger values.
Overview
Every new SheerID program starts in Test Mode — an emulation of the live verification experience. Because test mode does not consult real data sources, the outcome of a verification is driven by the firstName you submit (see the triggers below). In test mode:
- Successful verifications return a hashed placeholder reward, not a live reward code.
- Requests are not billable.
- Verification limits aren’t enforced. Fraud rules still run, so you can reproduce a fraud rejection.
- SheerID-hosted forms show a red Test Mode banner.
The same REST endpoints and JavaScript library are used for test and live — there is no separate test host. A program’s mode (and its testing allowlist) is configured in MySheerID.
Test Mode vs Live Mode testing
There are two ways to exercise test behavior:
Test Mode (pre-launch). The whole program is in a test state. Use it before launch to verify styling, copy, links, CTAs, and webhooks end to end.
Live Mode testing (post-launch). Once a program is live, add specific email addresses (up to 20) to the program’s testing allowlist in MySheerID. A verification submitted with an allowlisted email gets test-mode behavior (hashed reward, not billable), while every other consumer goes through real verification.
Simulate outcomes by first name
In test mode, the firstName you submit drives the outcome. Set it to one of these values (matching is case-insensitive) to force a specific result. Any other first name returns a successful verification.
firstName |
Outcome |
|---|---|
UPLOAD |
Routes straight to the document-upload step. |
REJECTED |
Instant verification fails; routes to document upload if the program allows it. |
INCONCLUSIVE |
Returns a pending (inconclusive) result. |
EMAILLOOP |
Triggers the email-loop (confirm-your-email) step. |
SSO |
Triggers the Single Sign-On (SSO) step. |
LIMIT |
Fails with verificationLimitExceeded, as if the consumer had hit the program’s verification limit. |
__ERROR__ |
Simulates an unexpected system error. Read the caveat below before you rely on it. |
Birth date, SSN, ID number, and postal code don’t change the outcome, so any valid values work. Last name is the exception: it can trigger a fraud rejection (see below).
__ERROR__ isn’t a terminal state. The submission response returns currentStep: error, so a SheerID-hosted form shows the error step, but nothing is persisted. Fetch the verification’s details afterward and you get collectInfo, which drops the consumer back into the form. Use LIMIT or a rejecting last name when you need currentStep to stay on error.
Simulate an offer-protections rejection
Fraud rules are the one part of offer protections that still runs in Test Mode, and the firstName triggers don’t touch them. To get a terminal fraud rejection, submit a lastName that starts with reject (case-insensitive). The verification fails with fraudRulesReject and stays on currentStep: error when you fetch its details again.
reject out of live traffic.
What’s different from production
| Test Mode / allowlisted | Live | |
|---|---|---|
| Data sources | Not consulted (firstName drives the result) |
Consulted |
| Reward | Hashed placeholder | Real reward code |
| Billing | Not billable | Billable |
| Verification limits | Not enforced | Enforced |
| Fraud rules | Run | Run |
Going live
When you’re ready, switch the program out of Test Mode in MySheerID. After launch, use Live Mode testing (the allowlist above) to validate changes without interrupting real consumers — and remember to turn it off when you’re done.
Related
- REST API — the request/response loop you’re testing.
- Errors — interpret the error outcomes you simulate.
- Setting Up Webhooks — verify webhook delivery while testing.
- SheerID Knowledge Base: Testing pre-launch and Live Mode testing.