Docs menu
Guides
API reference
API reference
The InlineShield REST API: six endpoints on https://api.inlineshield.io. Every reference page is generated from the OpenAPI 3.1 file, which the API's contract tests check against the running server.
Last updated
Endpoints
| Endpoint | What it does | Authentication |
|---|---|---|
POST /api/v1/verify | Screen a sign-up | Secret API key |
POST /api/v1/check | Browser check (site key) | Site key and Origin |
POST /api/v1/siteverify | Redeem a check token | Secret API key |
GET /api/v1/reviews/{reviewId} | Get a held sign-up's review | Secret API key |
POST /api/v1/feedback | Report a screening's outcome | Secret API key |
GET /api/v1/health | Service health | None |
Authentication
Header X-Api-Key:
Your secret API key (bs_live_… or bs_test_…), from the console under Settings › Keys. Never put it in a browser or an app. The header name X-ApiKey is also accepted (deprecated).
The browser call /check is authenticated by the site key in its body and the browser's Origin, which must be one of the site key's domains. The site key is public.
OpenAPI and Postman
- openapi.json: the OpenAPI 3.1.0 description, with examples for test mode and the magic addresses, and the webhook events.
- inlineshield.postman_collection.json: a Postman collection generated from it, with
baseUrl,apiKey,siteKeyandoriginvariables.
From the OpenAPI file
The InlineShield API screens sign-ups for bonus abuse, fake accounts and bots, and gives one of three verdicts: ALLOWED, QUARANTINED (hold for review) or BLOCKED.
There are two ways to integrate:
- Server only: your backend calls
POST /api/v1/verifywith the player's email, IP and User-Agent. - Browser script and backend:
inlineshield.json your sign-up page callsPOST /api/v1/checkwith your site key and gets a single-use token; your backend sends that token toPOST /api/v1/siteverifywith its secret key and gets the decision.
A held sign-up (action: "hold") carries a reviewId. Poll GET /api/v1/reviews/{reviewId} or wait for the signup.approved / signup.rejected webhook. Report real outcomes with POST /api/v1/feedback.
Authentication
- Secret API key (
bs_live_…live,bs_test_…test), sent in theX-Api-Keyheader, for/verify,/siteverify,/feedbackand/reviews/{reviewId}. Keep it on your server. Create keys in the console under Settings › Keys. - Site key (
bs_site_…live,bs_site_test_…test), sent in thesiteKeyfield of the/checkbody. It is public. A check is accepted only from a browserOriginon the site key's list of domains.
Test mode
A test API key or a test site key puts the request in test mode. Test requests are screened and recorded (History shows them with "Show test data"), but they never count against your monthly quota and never create a review, a webhook, a label or alert data. Test traffic has its own per-minute limits, separate from live traffic: 300 per minute per account on each of /verify and /check (/check is also limited to 30 per minute per client IP), and 300 per minute per test key on /siteverify. On top of that, 10,000 test requests per account per UTC day (then 429 TEST_LIMIT).
In test mode these five addresses always give the same result without running the engine (the part before @ is case-insensitive; the domain must be exactly test.inlineshield.io):
| Address | decision | action | recommendedAction | riskScore |
|---|---|---|---|---|
| allow@test.inlineshield.io | ALLOWED | allow | allow | 0 |
| nobonus@test.inlineshield.io | ALLOWED | allow | allow_no_bonus | 30 |
| review@test.inlineshield.io | QUARANTINED | hold | review | 50 |
| kyc@test.inlineshield.io | QUARANTINED | hold | require_kyc | 60 |
| block@test.inlineshield.io | BLOCKED | block | block | 95 |
A live key screens these addresses like any other. A held test screening has no reviewId: test mode creates no review, so the signup.* webhooks cannot be triggered with test traffic. Use the console's "Send test ping" for a signed test.ping delivery.
Quota and rate limits
Each live /verify or /check screening counts against the monthly quota of your plan. Over the quota (after a grace margin) both answer 402 QUOTA_EXCEEDED until the next UTC month; /siteverify then answers { success: false, error: "QUOTA_EXCEEDED" } for a missing token. Live responses carry X-Quota-Limit, X-Quota-Used, X-Quota-Reset and X-Quota-State.
Per-minute limits answer 429 RATE_LIMIT_EXCEEDED with Retry-After (seconds). /verify, /siteverify and /feedback also send X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets); /check and /reviews/{reviewId} send only Retry-After, on a 429. Browser code can read the quota and rate-limit headers and Retry-After (they are listed in Access-Control-Expose-Headers).
Webhooks
InlineShield sends registration.allowed, registration.blocked, signup.approved, signup.rejected and test.ping (see webhooks). A held sign-up arrives as registration.blocked with data.decision: "QUARANTINED", and is resolved later by signup.approved or signup.rejected. The event names incident.created and registration.review_required can appear in an endpoint's subscription list (incident.created is there by default), but they are never sent: no delivery ever carries either name.
Errors
Errors are JSON: { "error": "CODE", "message": "…" }. Branch on error, not on message. A body that is not valid JSON gets 400 BAD_REQUEST; a body over 1 MB gets 413 PAYLOAD_TOO_LARGE.
/siteverify answers token problems with HTTP 200 and { "success": false, "error": "…" }.