From your first check to your production workflow.
A server-side API, a hosted customer experience and a workspace for the people reviewing results.
1. Create and verify your account
Create an account with your business name, work email and a password of 12–128 characters.
Accept the terms, then open the email from IDReady. Click the link and confirm your email. Links are single-use and expire after one hour. Resend is available from the verification screen, subject to a sending limit.
Your verified account opens a private workspace. The email you verified is also your customer support reply-to address.
Open Developers and create a sandbox key. You see the full key once. Save it in your server’s secret manager.
Create a simulated check with fictional details. Choose a plan and use a live key when you are ready for real checks.
Each account has its own checks, keys, billing and webhook settings. Existing Shopify store access is not automatically linked or transferred to a direct account. Password reset links expire after one hour and invalidate existing login sessions when used. Use Sign out on shared devices.
2. Your first sandbox check
Base URL: https://app.realidchecker.com/api/v2. Requests use HTTPS, JSON and a server-side bearer key. Test keys start with idr_test_; live keys start with idr_live_. The key selects the mode; a request body cannot switch it.
The response includes id, mode, status and verification_url. Open the URL to try the simulated flow. Sandbox checks never send customer email, never charge for verification and do not establish anyone’s identity. Use fictional data. They are limited to 100 creations per account per day.
For live checks, use a live key and choose the appropriate options. Send the returned URL through your authorised customer flow, or set send_email: true. An email status of accepted means the email provider accepted it; it does not prove inbox delivery or that the customer read it.
Send Authorization: Bearer YOUR_KEY on every request. Keys are hashed in storage. Rotating a key immediately revokes the previous key of the same mode. The API permits 120 requests per account per fixed minute across both modes. A 429 response includes Retry-After. Keep keys out of URLs, browser JavaScript, public repositories and customer emails. CORS access for public browser clients is not provided.
POST /verifications
Returns 201. Include a unique Idempotency-Key of 8–200 printable non-space ASCII characters. Repeating the same key and body returns the original check. A different body with the same key returns 409. While the first request is processing, retries return 409; retry the same key after a short delay. Keep the key stable across network retries.
Field
Type / default
Meaning
customer_email
string · required
Valid customer email, max 254 characters.
customer_name
string · required
Expected customer name, 2–120 characters. Used for name matching.
reference
string · empty
Your order or customer reference, max 64 characters. Does not grant access to a platform’s order.
require_selfie
boolean · true
Request selfie, liveness and face matching alongside the ID.
require_address
boolean · false
Request a supported proof-of-address document. Requires a configured live workflow.
require_signature
boolean · false
Ask the customer to review and electronically sign your agreement.
agreement_text
string · empty
Required when require_signature is true. Max 10,000 characters. Confirm the agreement is suitable for your use case.
send_email
boolean · false
Ask IDReady to email the secure link in live mode. Always ignored in sandbox.
Unknown fields are rejected. ID document verification is always included. No ID photographs, document numbers or birth dates are accepted through this endpoint.
GET /verifications/{id}
Returns one check from the authenticated workspace and key mode, or 404 if it does not belong to both. The response includes customer name/email, reference, timestamps, selected requirements, results and review flags. It never returns ID image bytes or document numbers.
Query parameters: limit (1–100, default 50) and before (a verification ID). Results are newest first. The response is {"data": [...], "has_more": true, "next_before": 123}. Pass next_before as the next request’s before. Records are isolated by account and test/live mode.
Response fields and statuses
pending: link created; in_progress: customer started; approved: check passed; declined: check did not pass; needs_review: manual review required; expired: link expired; cancelled: withdrawn by the account owner. A missing result is null, not a pass.
checks contains document_type, issuing_country, name_match, address_match, live_person, face_match_score, document_expired, ip_country, attempts, proof_of_address_required/approved, signature_required/approved. flags is an array of review warnings. decided_by distinguishes the origin of a decision. The direct API does not have Shopify shipping/billing addresses to compare; address_match can be unavailable even when a requested proof-of-address check passes.
Error handling
400: invalid idempotency header or malformed request.
404: record unavailable to this account and key mode.
409: idempotency conflict or request still processing.
422: invalid fields, missing signature agreement or unavailable check requirements.
429: rate limit.
503: a required live service is not configured.
HTTP errors use {"error":{"message":"..."}}; field-validation errors use FastAPI’s detail array. Retry transient connection failures using the same idempotency key with exponential backoff. Do not create a fresh check on every retry.
4. Server-side SDKs
These are downloadable IDReady source SDKs, version 0.1.0. They are not published npm or PyPI packages. Review them, keep them server-side, and pin the version you deploy.
Python 3.10+
Download idready.py ↓ · Uses only Python’s standard library. Save as idready.py in your server project.
import os
from idready import IDReady
client = IDReady(os.environ["IDREADY_API_KEY"])
check = client.create_verification(
{"customer_email": "alex@example.com", "customer_name": "Alex Morgan",
"reference": "Order #1048", "require_selfie": True},
idempotency_key="order-1048-check-1",
)
print(check["verification_url"])
result = client.get_verification(check["id"])
JavaScript · Node.js 18+
Download idready.mjs ↓ · Uses native fetch and AbortController. Do not bundle it into your customer-facing frontend.
Both SDKs support create, get and list methods, a 30-second request timeout and webhook signature verification. They do not automatically retry requests or store your credentials.
5. Signed verification webhooks
Open Developers in your dashboard and enter a public HTTPS endpoint.
Save and copy the signing secret. Saving again rotates it immediately.
Read the raw request bytes before parsing JSON.
Verify the HMAC and timestamp, then validate the payload’s mode and deduplicate the event for your application.
Headers: X-IDReady-Event, X-IDReady-Timestamp (Unix seconds), X-IDReady-Signature. Expected signature is lowercase hex HMAC-SHA256 over timestamp + "." + raw_body, using your signing secret. Reject timestamps more than five minutes from your server clock; compare signatures in constant time.
from idready import verify_webhook
if not verify_webhook(secret, raw_body, timestamp_header, signature_header):
# Return 400; do not process the body.
raise ValueError("Invalid webhook")
Event: verification.completed. Payload includes id, mode, status, decided_by, order, customer, checks, flags and completed_at. Treat the verification ID, status and completed_at as your deduplication key. A later manual decision may update a result; preserve the latest authorised decision.
Return a 2xx response promptly. Delivery makes up to three attempts with delays of 0, 2 and 10 seconds; there is no durable multi-day webhook queue. Use API polling for reconciliation and downtime recovery. The list endpoint is cursor-paginated. Do not assume every event arrives once or in order. Sandbox decisions can trigger webhooks and are marked mode: test.
6. WordPress, WooCommerce and other platforms
The direct REST API works from a custom server integration. An official WordPress.org or WooCommerce Marketplace plugin has not been published as part of this release.
Create a direct IDReady account and save a server-side API key outside the public web root. Use your host’s secret manager or a protected server configuration.
From an authorised order action in your plugin/backend, read the actual order’s customer name and email. Check the operator’s capability and WordPress nonce before starting a request.
POST to the API using WordPress’s wp_remote_post, with a stable idempotency key for that order and check attempt. Never put the secret in frontend JavaScript, a shortcode or an email.
Persist the returned IDReady verification ID against the order. Use WooCommerce order CRUD methods for HPOS compatibility; do not write directly to wp_posts or assume a post ID schema.
Display the secure verification URL only to the authorised customer or operator, or select email delivery. Do not redirect visitors without checking their order access.
Register a dedicated server endpoint for signed webhooks. Read the raw body and verify HMAC/timestamp before trusting it. Map the verification ID to your own order before changing anything.
Only your integration decides whether to hold, release, cancel or fulfil an order. A verification result is supporting evidence, not a guarantee of payment authorisation.
Use the same pattern for Magento, Wix, BigCommerce and custom applications. Platform authentication, checkout blocks, catalogue access, automatic fulfilment actions and marketplace submissions are separate integrations; they are not supplied by the neutral API itself.
Existing Shopify integration
Shopify merchants continue using the embedded app and Shopify Billing. Their existing API is /api/v1/verifications, which requires a Shopify order_id. It reads the customer from that store’s order. Direct v2 keys and accounts do not authorise v1 calls or grant Shopify store access.
7. Plans, trial and Stripe billing
Direct accounts start with a 7-day trial of 5 completed live checks after signup; the trial clock starts when the account is created. Sandbox is separate. Paid plans are Starter $19 / 25 checks, Growth $59 / 120 checks and Scale $199 / 400 checks, per month in USD. Every paid plan includes the available check options.
Pending checks reserve capacity so that simultaneous requests cannot exceed your allowance. Completed approved, declined and needs-review checks consume it. Expired or cancelled unfinished checks release their reservation. There are no automatic direct-account overage charges; new live requests stop at the allowance. Sandbox has its own daily limit.
Checkout is hosted by Stripe. Payment details do not pass through IDReady. Clicking a success-page link does not activate a plan: IDReady waits for a signed Stripe event and verifies the subscription against Stripe. If confirmation is delayed, refresh Plan & billing or contact support. Incomplete, past-due, unpaid, cancelled or expired subscriptions cannot create new live checks.
Use Manage billing for invoices, payment methods and cancellation at the end of the current paid period. Plan switching is not currently offered in the portal; contact support before changing an existing plan. If checkout is still being configured, the dashboard clearly says so and does not accept a payment. No demo checkout is presented as live.
8. Data handling and operational security
Customers begin on an IDReady verification page, with Didit handling identity capture and processing. Checks may include a government-issued ID, selfie, proof of address or agreement depending on the selected requirements. Do not claim that all verification data remains on the customer’s phone.
The direct API exposes outcome data, not ID images or document numbers. Configure evidence retention in Settings (immediate deletion after decision, or 30–730 days). Evidence retention follows the existing verification engine; deletion from backup/archive systems and provider obligations is described in our policies. The direct dashboard currently shows results, not the Shopify evidence viewer or printable chargeback report.
API keys are hashed and action tokens are single-use and hashed. Account forms use CSRF protection. Authentication pages exclude marketing analytics and third-party scripts; verification/reset tokens are carried in URL fragments then removed from the address bar. Never share a verification link publicly: it is a bearer link for the customer’s check.
Only request verification when you have the authority and appropriate customer notices for your use case. Review Privacy, Terms and the Data processing addendum. An approved identity check does not establish that a person authorised a particular card payment. Determine your own review and fulfilment policy.
9. Troubleshooting
Verification email missing: check spam, confirm the email you entered and use Resend. If the email provider is unavailable, the interface says the message was not sent.
Link expired: request a new email-verification/reset link. Customer-check expiry is separate.
401: check the key prefix, bearer header and latest rotation. Test and live keys are distinct.
402: inspect trial/plan status and used/reserved checks. Wait for billing confirmation if you just checked out.
409: use the original body and idempotency key. Wait briefly if the request is still processing.
Webhook missing: verify HTTPS reachability, signature handling and your logs. Poll the API to reconcile after downtime.
Address/signature unavailable: check the selected workflow requirements. A signature request must include agreement text.
Sandbox result looks real: it is still a simulation. Check the mode field before taking order actions.
Contact support@realidchecker.com with your verification ID, timestamp and HTTP status. Do not email API keys, passwords, full identity documents or card details.