Shop check API
You send a shop address and get back the same check as on our website: verdict, trust score and the reasons behind it. That lets you build, for example, a warning before payment or a pre-check for support.
{ "url": "https://beispiel-shop.example" }{
"domain": "beispiel-shop.example",
"score": 82,
"verdict": "safe",
"checkedAt": "2026-09-28T10:15:32.000Z",
…
}Shown on the websiteNo major warning
Fictional example with a made-up address (.example).
Three steps to your first result
Create an account
Sign up for the developer portal. 100 credits are free every month, one check costs one credit.
Create a key
Create a key under API keys. It starts with fsk_live_ and is shown only once. Store it on your server as the environment variable FAKESHOP_API_KEY.
export FAKESHOP_API_KEY="fsk_live_…"Send your first call
POST the shop address to https://api.fakeshop.ai/api/check. On 200 the result is in the response, on 202 you poll the status until it is ready.
Your first API call
Request to https://api.fakeshop.ai/api/check and a complete example response. The code samples cover the full flow including status polling and read the key from the environment variable FAKESHOP_API_KEY.
# 1. Request the check
curl -sS -X POST "https://api.fakeshop.ai/api/check?lang=en" \
-H "Content-Type: application/json" \
-H "x-api-key: $FAKESHOP_API_KEY" \
-d '{"url":"https://beispiel-shop.example","checkType":"shop"}'
# 2. Only on status 202: poll the status with the jobId until "completed" or "failed".
# Recommended: after 2 s, then every 3 to 5 s, give up after 3 minutes. Polling costs no credit.
curl -sS "https://api.fakeshop.ai/api/check/status/JOB_ID"Point at a field name or tap it to see what the field contains.
{: "beispiel-shop.example",: 82,: "safe",: "shop",: true,: "2026-09-28T10:15:32.000Z",: { "level": 4, "label": "no findings" },: "high",: "fashion",: "none",: "Fictional example: no clear warning signs in the features checked.",: "Still pay with a method that offers buyer protection.",: [{: "tradeRegister",: "Commercial register",: "ok",: "positive",: ["The company from the legal notice is registered under the stated number."]},{: "domainAge",: "Domain age",: "ok",: "positive",: ["The domain has been registered for 47 months."],: { "ageMonths": 47 }}],: [{: "tradeRegister",: "Commercial register",: "ok",: "positive",: ["…"]}],: {"kind": "ai","text": "Automated assessment, partly generated with AI. No guarantee, not legal advice. Liability as set out in our terms of use.","aiInvolved": true,"regulation": "EU 2024/1689 Art. 50","termsUrl": "https://fakeshop.ai/en/terms","methodUrl": "https://fakeshop.ai/en/methodology#ki-einsatz"}}verdictsafe | suspicious | danger | not_a_shop | unreachable
Overall assessment.
verdict is a code value. The website shows safe as “No major warning”. All values
Access and limits
- 50
Without a key
checks per day and IP address, free of charge
- 100
With a key
credits per month for free, then 1 credit per check from your balance
- 20
Short-term limit
checks per minute and IP address, with or without a key (429 too_many_requests)
- JSON
Format
JSON over HTTPS, texts in German or English
Base URL
- Servers, cron jobs, WordPress
https://api.fakeshop.aiFor all calls from servers. This address goes straight to our server, without a Cloudflare check in front.- Browser on fakeshop.ai
https://fakeshop.ai/apiRemains valid and serves our own website. Calls from data centres receive a Cloudflare challenge there: HTTP 403 with the header cf-mitigated: challenge and an HTML page instead of JSON.
The key belongs on your server. Third-party websites cannot call the API from the browser (CORS), and a key in frontend code would be readable by every visitor.
Authentication with an API key
Send the key in the x-api-key header. The header name is case-insensitive. Without a key, requests use the free quota per IP address. You create the key in the developer portal. With an account, 100 credits per month are free. We answer integration questions at [email protected].
x-api-key: fsk_live_…We store keys only as a hash. A lost key therefore cannot be shown again. You delete it and create a new one. You can set a daily limit per key.
Quotas and limits
Without a key, 50 checks per day and IP address are free. With a key, each check deducts one credit. All requests are also subject to a short-term limit of 20 checks per minute per IP address.
| Status | Error code | When |
|---|---|---|
401 | invalid_api_key | Key unknown, copied incorrectly or deleted. |
402 | insufficient_credits | The credit balance is used up. |
429 | quota_exceeded | Daily quota without a key used up, or the daily limit you set on the key reached. Retry-After gives the seconds until midnight UTC. |
429 | too_many_requests | More than 20 checks per minute per IP address. |
What costs a credit
- Costs one credit
- Every accepted check with a key: response 200, also for stored results (cached: true) and for the verdicts unreachable or not_a_shop, as well as response 202.
- Free
- Input errors (400), rejected requests (401, 402, 403, 429) and every status poll.
- Refunded
- If the check fails (500 scan_failed, 504 scan_timeout or status failed), the credit is returned automatically. The portal statement then shows a refund.
- Remaining balance
- After every paid check, the header X-RateLimit-Remaining states your balance in credits. The 100 free credits are added by the first check of a calendar month (UTC).
Systematic scraping or abuse of the free quotas is prohibited and may lead to the IP address being blocked. For higher limits or production integrations, write to [email protected].
Fetch the result
POST /api/check responds with 200 when a stored result exists. If a new check is needed, you get 202 with a jobId and fetch the result with GET /api/check/status/<jobId>. A new check usually takes a few seconds, longer for slow or blocking sites.
POST /api/check
Response 200 with the result, or 202 with { "status": "queued", "jobId", "domain" }.
GET /api/check/status/<jobId>
First poll after 2 seconds, then every 3 to 5 seconds. No key needed, costs no credit.
Result or give up
On completed, the result is in result, in the same shape as the 200 response. After 3 minutes without a result, stop and ask again later.
Status poll responses
| HTTP | Body | Meaning and next step |
|---|---|---|
| 200 | { "status": "queued" } | Waiting in the queue. Keep polling. |
| 200 | { "status": "processing" } | Being checked right now. Keep polling. |
| 200 | { "status": "completed", "result": { … } } | Done. result contains the check result. |
| 200 | { "status": "failed", "errorCode": "scan_failed" } | Check failed. Stop polling; the credit is refunded. |
| 404 | { "errorCode": "job_not_found" } | jobId unknown or expired. Jobs remain retrievable for one hour after they finish. After that, send POST /api/check again; if the result is stored, it comes back with 200. |
The status poll has its own short-term limit of 120 requests per minute and IP address. If you check many shops at once, poll the open jobs one after another.
What the verdict values mean
The verdict field always returns an English code value. Our website shows verdict words for it; safe appears as “No major warning”, never as “safe”. A code value is not a recommendation, it summarises the features checked as of the check date.
| verdict | Shown on the website* | Meaning |
|---|---|---|
safe | No major warning | No substantiated warning signs in the features checked. Not a recommendation and not a guarantee. |
suspicious | Suspicious | A mixed picture: some features count in the shop’s favour, others are missing or unclear. |
danger | Danger | Several serious warning signs or an entry on an evaluated warning list. |
not_a_shop | Not a shop | The address does not lead to an online shop. score is null. |
unreachable | Not verifiable | The site could not be reached. score is null. |
API reference
POST /api/check accepts these parameters.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
url | Body | string | Yes | The shop or website URL to check. |
checkType | Body | shop | website | No | Check profile. Default is shop. website allows a credibility check when the URL is not an online shop. |
force | Body | boolean | No | Forces a new check instead of a stored result. Runs without the queue and only responds with the finished result, so it can take considerably longer. Costs one credit like any check. |
lang | Query | de | en | No | Language of the text fields (summary, recommendation, reasons). Alternatively via Accept-Language. Default is de. |
GET /api/check/status/<jobId> only takes the jobId from the 202 response in the path. No key is needed there.
Top-level fields:
| Field | Type | Description |
|---|---|---|
domain | string | Checked domain without protocol. |
score | number | null | Trust score from 0 to 100, higher means more trust. null for not_a_shop, unreachable or while the result is under manual review. |
verdict | safe | suspicious | danger | not_a_shop | unreachable | Overall assessment. |
checkType | shop | website | Applied check profile. |
productCategory | string | null | Product category of the shop, e.g. electronics or fashion, if detected. |
fakeshopStatus | none | suspected | confirmed | none, suspected or confirmed. confirmed means: a warning-list match or manual confirmation. |
trustLevel | { level, label } | level is 1 to 5 (machine-readable), label is a language-dependent display text. |
confidenceBand | high | medium | low | How reliable the data basis for this assessment is. |
summary | string | null | Short, language-dependent summary of the result. |
recommendation | string | null | Plain-text recommendation for action. |
factors | Factor[] | The individual features: { id, label, status, impact, reasons[], display? }. |
topSignals | Factor[] | The most notable features, same shape as factors. |
aiContent | object (optional) | Present only if the response contains text from a language model: regulation (EU 2024/1689 Art. 50), digitalSourceType, label and the list of affected fields in fields. Anyone who publishes these texts must label them themselves under Art. 50(4) AI Act. |
notice | { kind, text, aiInvolved, termsUrl, methodUrl } | Note on the classification: kind states its origin (ai = own check with a language model, auto, list, directory, manual, reports), text is the sentence on warranty and liability, aiInvolved says whether a language model took part. termsUrl leads to the terms of use, methodUrl to the methodology. If you display a verdict or the trust score, display this note with it. |
cached | boolean | true if the result comes from an earlier check (see checkedAt). |
checkedAt | string (ISO 8601) | Timestamp of the (most recent) check. |
faviconUrl | string | null | Favicon of the checked domain, if available. |
previewImage | string | null | Image of the home page if available; usually null. |
Fields per entry in factors / topSignals:
| Field | Type | Description |
|---|---|---|
id | string | Stable code of the feature, e.g. impressum, domainAge, fakeshopLists. |
label | string | Language-dependent display name. |
status | ok | warn | fail | unknown | Result of this individual feature. |
impact | positive | negative | neutral | Effect on the trust score. |
reasons | string[] | Language-dependent reasoning sentences. |
aiGenerated | true (optional) | true if a language model wrote the reasons of this feature. The same flag appears as display.aiGenerated on the research summary of the reputationCheck feature (display.summary). If you publish these texts, label them under Art. 50(4) AI Act. |
display | object (optional) | Additional, harmless display values (e.g. domain age in months). |
POST /api/check returns these headers for limits and balance.
| Header | Description |
|---|---|
X-RateLimit-Remaining | With a key: remaining balance in credits after this check. Without a key: checks left today. |
X-RateLimit-Limit | Daily limit. Always present without a key; with a key only when a daily limit on the key applies. |
X-RateLimit-Reset | Seconds until the daily limit resets at midnight UTC. |
Retry-After | On 429: seconds after which a new request makes sense. |
RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset | State of the short-term limit (checks per minute and IP address). |
In addition to a human-readable error text, error responses always contain a stable errorCode field. Build your error handling against errorCode. The text can differ depending on the lang parameter.
| Code | HTTP status | Meaning | What to do |
|---|---|---|---|
invalid_json | 400 | The body is not valid JSON. | Check the JSON and set Content-Type: application/json. Costs no credit. |
url_required | 400 | url is missing from the request body, or the value is not a string. | Send url as a string in the JSON body. Set Content-Type: application/json. |
invalid_url | 400 | The address is empty, too long, or points to an IP address or an internal network. | Send a public shop address with a domain name, for example example-shop.com. |
invalid_check_type | 400 | checkType contains an unknown value. Only shop and website are allowed. | Omit checkType or send shop or website. |
invalid_api_key | 401 | The provided X-Api-Key is invalid, unknown or has been blocked. | Copy the complete key (starts with fsk_live_). If it is lost, delete it in the portal and create a new one. |
insufficient_credits | 402 | The key’s credit balance is used up. | Top up your balance in the portal. Do not retry until then. |
quota_exceeded | 429 | The keyless daily quota or the key’s daily limit has been reached. Retry-After states the seconds until midnight UTC. | Retry after Retry-After. Without a key: use a key. With a key: raise or remove the daily limit in the portal. |
too_many_requests | 429 | Short-term burst limit exceeded, independent of the daily limit. | Wait for Retry-After and spread requests more evenly. |
origin_not_allowed | 403 | Call from the browser of a third-party website (CORS). | Call the API from your server; the key does not belong in the browser. |
scan_failed | 500 / 200 | The check failed: directly as 500 or in the status poll as { "status": "failed" }. | The credit is refunded. Try again later; if the error persists, report it to [email protected]. |
scan_timeout | 504 | A check without the queue (for example with force: true) took longer than 55 seconds. | The credit is refunded. Send again without force so the check runs through the queue. |
job_not_found | 404 | Status query only: the jobId is unknown or has expired. | Send POST /api/check again. Stored results then come back with 200. |
job_status_failed | 503 | Status poll only: the job status could not be determined right now. | Continue with the next poll. |
queue_unavailable | 503 | Status query only: the queue is currently unavailable. | Wait a few seconds and poll again. |
HTTP 403 with HTML and the header cf-mitigated: challenge comes from Cloudflare in front of fakeshop.ai. Fix: use the base URL https://api.fakeshop.ai.
Machine-readable description (OpenAPI 3.1) for generating clients: /api/openapi.json
Try it with your own key
The console sends real requests to POST /api/check, polls the status on 202 and shows status code, headers and body unchanged. Your key stays in this browser: it is only sent as a header to fakeshop.ai and is kept at most in this tab’s storage.
Response
- Request
- Status poll
- Result
No request sent yet.
No request sent yet.
# 1. Request the check
curl -sS -X POST "https://api.fakeshop.ai/api/check?lang=en" \
-H "Content-Type: application/json" \
-H "x-api-key: $FAKESHOP_API_KEY" \
-d '{"url":"https://beispiel-shop.example","checkType":"shop"}'
# 2. Only on status 202: poll the status with the jobId until "completed" or "failed".
# Recommended: after 2 s, then every 3 to 5 s, give up after 3 minutes. Polling costs no credit.
curl -sS "https://api.fakeshop.ai/api/check/status/JOB_ID"The code uses the base URL https://api.fakeshop.ai and reads the key from the environment variable FAKESHOP_API_KEY. The key you entered does not appear in the code.
Public endpoints without a key
The two endpoints below are public. The button calls them from your browser and shows the response unchanged.
Recorded response from 3 October 2026 (not fetched yet)
{
"totalChecks": 79554,
"fakeShopsDetected": 37513,
"cleanShops": 42036,
"checksToday": 0,
"fakeQuota": 0.4715413429871534,
"updatedAt": "2026-10-03T12:10:29.861Z"
}Equivalent to this call: curl "https://api.fakeshop.ai/api/stats"
The numbers and domains in the live response change with our data. For fields and status codes, follow the reference above.
About the stats response: fakeQuota is fakeShopsDetected divided by totalChecks (0.47 equals 47%). checksToday counts the checks since UTC midnight, so the value is close to 0 shortly after midnight.
Caching and privacy
Stored results
We store every result per domain and serve it again while it is valid: unclear results (suspicious) and special cases for up to 7 days, clear verdicts (safe, danger) for up to 90 days, manually classified domains for up to 365 days. If a site was last unreachable, the next request checks it again.
cached: true and checkedAt show whether and when the check ran. If you cache results yourself, base their validity on checkedAt. force: true forces a new check.
Privacy
Send only the shop address. Paths and parameters containing your customers’ data, such as email addresses, order numbers or tokens, do not belong in url.
Check results refer to the shop and are public: a result page for a checked domain may appear on fakeshop.ai.
For every key we store a hash instead of the plain text, the number of requests per day and, per day, the requesting IP addresses with counts. You see this overview in the portal under API keys. Privacy policy.
Credit prices
One credit equals one check. You buy credits once in the developer portal, without a subscription. Prices as of: 02/10/2026.
Starter
100credits
€4.90
€0.049 per check
Standard
1,000credits
€24.00
€0.024 per check
Pro
5,000credits
€89.00
€0.018 per check
Business
25,000credits
€299.00
€0.012 per check
Free: 100 credits per month with an account, 50 checks per day and IP without a key.
Changes and version
The API has one response shape without a version parameter. New fields may be added. Treat unknown fields as optional and your integration stays unaffected.
- Base URL https://api.fakeshop.ai for server calls.
- Input errors (400) no longer cost a credit. New error codes invalid_url, invalid_json, scan_timeout and origin_not_allowed.
- Failed checks are refunded automatically.
- Status poll with its own short-term limit of 120 requests per minute and IP address.
- Console on this page and in the portal to try the API with your own key.
- OpenAPI description at /api/openapi.json.
Further public endpoints
These endpoints need no key and cost no credits.
GET /api/warnlistParameterslimit (default 50, max 1000), offset
ReturnsDomains on the warning list with category and check date
GET /api/fakeshopsParameterslimit (default 50, max 200)
ReturnsListed shops (warning list or assessment Danger) with product category
GET /api/statsParametersnone
ReturnsTotals: domains checked, shops listed, timestamp
GET /api/iban-checkParametersiban (max. 30 requests per minute and IP)
ReturnsWhether there are approved reports for this IBAN, count, date of the first
A key for production use
You create the key yourself in the developer portal; 100 credits per month are free. Integration questions, higher volumes and bug reports go to [email protected].