Docs menu

API reference

POST /api/v1/feedback

Report a screening's outcome. Report what a player turned out to be. Generated from the OpenAPI file.

Last updated 2026-11-03

Overview

POST https://api.inlineshield.io/api/v1/feedback

Tell InlineShield what a screened player turned out to be (fraud or legit), by the requestId the API returned or by the /check token. Accepted for screenings up to 180 days old by requestId; a /check token is kept for about a day after the screening, so later feedback must use the requestId. Sending the same feedback again changes nothing (changed: false).

Feedback on a test screening is accepted but never recorded (changed: false). Limited per key to your plan's per-minute limit; never counted against the quota and accepted while the account is over it.

Authentication

Send your secret API key in the X-Api-Key header.

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).

Request body

JSON (Content-Type: application/json), required.

Send exactly one of requestId or token.

Field	Type	Required	Description
`requestId`	string	no	The requestId the API returned.
`token`	string	no	The /check token. A token is kept for about a day after the screening; for later feedback send the requestId (/siteverify returns it).
`outcome`	string	yes	Values: `fraud, legit`
`category`	string or null	no	Values: `bonus_abuse, multi_account, chargeback, kyc_failed, bot, good_customer, other, null`
`note`	string or null	no	At most 200 characters after trimming. Never shown to other operators.at most 200 characters

Request examples

{
  "requestId": "AUD-MHH3K33H-5B9D1F3A7C02",
  "outcome": "fraud",
  "category": "bonus_abuse",
  "note": "Second account, same payment card."
}

{
  "token": "bst_q3Jm0b8vN2kXo7rT5wYz1cE4hL6pA9sD0fG2jK8uV3i",
  "outcome": "legit"
}

The first example as a cURL command:

cURL

curl -X POST https://api.inlineshield.io/api/v1/feedback \
  -H "X-Api-Key: $INLINESHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "requestId": "AUD-MHH3K33H-5B9D1F3A7C02",
  "outcome": "fraud",
  "category": "bonus_abuse",
  "note": "Second account, same payment card."
}'

Responses

`200 OK`

Accepted. changed is false when nothing new was recorded (the same feedback again, or a test screening).

Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Field	Type	Required	Description
`success`	true	yes
`outcome`	string	yes	Values: `fraud, legit`
`category`	string or null	yes	Values: `bonus_abuse, multi_account, chargeback, kyc_failed, bot, good_customer, other, null`
`changed`	boolean	yes

{
  "success": true,
  "outcome": "fraud",
  "category": "bonus_abuse",
  "changed": false
}

{
  "success": true,
  "outcome": "legit",
  "category": null,
  "changed": false
}

`400 Bad Request`

Not exactly one of requestId or token, a bad outcome, category or note, or (without the rate-limit headers) a body that is not valid JSON.

Headers: X-RateLimit-Limit (optional), X-RateLimit-Remaining (optional), X-RateLimit-Reset (optional).

Field	Type	Required	Description
`error`	string	yes	Values: `BAD_REQUEST`
`message`	string	yes

`401 Unauthorized`

No X-Api-Key header, or an unknown, revoked or expired key.

Field	Type	Required	Description
`error`	string	yes	Values: `UNAUTHORIZED, INVALID_API_KEY, EXPIRED_API_KEY, ORGANIZATION_NOT_FOUND`
`message`	string	yes

{
  "error": "UNAUTHORIZED",
  "message": "Access denied: Missing required X-Api-Key header."
}

{
  "error": "INVALID_API_KEY",
  "message": "Invalid API key provided."
}

`403 Forbidden`

The account is suspended.

Field	Type	Required	Description
`error`	string	yes	Values: `TENANT_SUSPENDED`
`message`	string	yes

`404 Not Found`

No such screening in this account.

Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Field	Type	Required	Description
`error`	string	yes	Values: `NOT_FOUND`
`message`	string	yes

`422 Unprocessable Content`

The screening is more than 180 days old.

Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Field	Type	Required	Description
`error`	string	yes	Values: `SCREENING_TOO_OLD`
`message`	string	yes

`429 Too Many Requests`

The per-minute limit of this key.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Field	Type	Required	Description
`error`	string	yes	Values: `RATE_LIMIT_EXCEEDED`
`message`	string	yes

`500 Internal Server Error`

Internal error.

Field	Type	Required	Description
`error`	string	yes	Values: `FEEDBACK_ERROR, AUTH_ERROR`
`message`	string	yes

`503 Service Unavailable`

The key could not be checked right now. Try again.

Field	Type	Required	Description
`error`	string	yes	Values: `DATABASE_ERROR`
`message`	string	yes

Errors

Errors are JSON, { "error": "CODE", "message": "…" }. Branch on error, never on message.

HTTP status	error	When
`400`	`BAD_REQUEST`	Not exactly one of `requestId` or `token`, a bad `outcome`, `category` or `note`, or (without the rate-limit headers) a body that is not valid JSON.
`401`	`UNAUTHORIZED`, `INVALID_API_KEY`, `EXPIRED_API_KEY`, `ORGANIZATION_NOT_FOUND`	No `X-Api-Key` header, or an unknown, revoked or expired key.
`403`	`TENANT_SUSPENDED`	The account is suspended.
`404`	`NOT_FOUND`	No such screening in this account.
`422`	`SCREENING_TOO_OLD`	The screening is more than 180 days old.
`429`	`RATE_LIMIT_EXCEEDED`	The per-minute limit of this key.
`500`	`FEEDBACK_ERROR`, `AUTH_ERROR`	Internal error.
`503`	`DATABASE_ERROR`	The key could not be checked right now. Try again.

See all errors for every endpoint.

Headers and limits

Response header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current one-minute window.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	Seconds until the current window ends.
`Retry-After`	Seconds to wait before trying again.

The limits per endpoint and plan are on Rate limits and quotas.