Overview

The Feedback loop API enhances your application’s bot detection model by sending fraud/FN/FP incidents. It allows a better incident response, tailored-made accuracy and advanced reporting.
We support two reporting options:

Online reporting: Report in real-time/near real-time to the PerimeterX Feedback loop API
Offline reporting: Report to a specified bucket from which PerimeterX will pull the data daily

Online Reporting

Request

URL

Contact support to get your app-specific URL

Method

POST

application/json

Content-Type

application/json

Authorization

Bearer ¹

Limitations

Rate limit - 150 api calls / minute
Payload size - max 10MB / request

Parameters

Array of JSON

Name	Type	Required	Values	Description
id_type	String	V	“vid”/ “custom_id”`	VID - PerimeterX unique visitor ID (as provided by PerimeterX).
id_value	String	V		The VID / Custom_id value
app_id	String	V		PerimeterX application ID
timestamp	epoch	V		Epoch in milliseconds
is_user_malicious	Boolean	V	true / false
additional_data	Object	Optional		JSON object in the format of {key1: value1, key2: value2, ….} ²

Example

[{
     “id_type”: “vid”,
     “id_value”: “value”,
     “app_id”: “value”,
     “timestamp": 1591898505000,
     “is_user_malicious": true,
     “additional_data": {
        “certainty_score”: 100,
        “converted_user”: true
    }
 },
 {
    "id_type": "session_id",
    "id_value": "value",
    "app_id": "value",
    "timestamp": 1591898505000,
    "is_user_malicious": false,
    "additional_data": {
         "stolen_credit_card": true,
         "session_id": “custom_param3” 
     }
}]

¹ This is different from the enforcer token, and is sent separately. Each token is associated to only one app_id
² Custom identifier of the customer (e.g session_id). This should be provided as a custom param on integration (enforcer) and added in additional data with the matching custom parameter. For example: “custom_id_name”: “custom_param3”

Response

Success response	200 { success: true, message: ok }
Response Headers	X-RateLimit-Limit: 150 X-RateLimit-Remaining: Int, remaining requests in time window X-RateLimit-Reset: epoch UTC seconds , next window reset
Failure response(s)	Status codes: 400, 401 , 404, 413, 429, 500 { success: bool message: string errors: [] }
Partial success	200 { success: true, message: “see errors section for more details”, errors: [“request at index - ”] }
Missing or Invalid header	400 { success: false, message: “see errors section for more details”, errors: [“missing or invalid header: ‘ :’“] } 400 (In case of Authorization header) { success: false, message: “see errors section for more details”, errors: [“missing or invalid header: ‘Authorization’“] }
Unsupported method	400 { success: false, errors: [“endpoint does not support the HTTP method:’“] }
Malformed request body	400 { success: false, message: “see errors section for more details”, errors: [“invalid body stream“] }
Request fields are missing or have invalid values	400 { success: false, message: “see errors section for more details”, errors: [“request at index - unexpected format: ‘’ parameter is missing or has invalid value in request body“] }
Unauthorized	401 { success: false, message: “see errors section for more details”, errors: [“unauthorized“] }
Invalid endpoint	404
Payload too large	413 { success: false, message: “see errors section for more details”, errors: [“payload too large, expecting max 10 MB“] }
Too many requests	429 { success: false, message: “see errors section for more details”, errors: [“too many requests“] }
Server error	500 { success: false, message: “see errors section for more details”, errors: [“request at index - unexpected error“] }

Offline reporting

Configuration

S3 Bucket details

Contact PerimeterX with the following details:

Name
Region
Access key
Secret key
Encryption type³

Access

Provide PerimeterX with the following permissions for the bucket:
ListBucket
GetObject
PutObject⁴

Limitations

File size - max 100MB / file

Validation

File content will be validated against MD5 checksum
- Each line will be validated by Parameters requirement

Schedule

PerimeterX will process the files daily from the last successful scan to the current date/time

Folder structure

yyyy-mm-dd

File name

Each file name will contain a suffix of it’s MD5 checksum content

File Content

Separated lines of JSONs

Name	Type	Required	Values	Description
id_type	String	V	“vid”/ “custom_id”`	VID - PerimeterX unique visitor ID (as provided by PerimeterX).
id_value	String	V		The VID / Custom_id value
app_id	String	V		PerimeterX application ID
timestamp	epoch	V		Epoch in milliseconds
is_user_malicious	Boolean	V	true / false
additional_data	Object	Optional		JSON object in the format of {key1: value1, key2: value2, ….}

Example

{  “id_type”: “vid”,  “id_value”: “value”,  “app_id”: “value”,  “timestamp": 1591898505000, “is_user_malicious": true,  “additional_data": {  “certainty_score”: 100, “converted_user”: true } }
{  "id_type: session_id,  "id_value": "value",  "app_id": "value",  "timestamp": 1591898505000, "is_user_malicious": false,  "additional_data": {  "stolen_credit_card": true,  "session_id": “custom_param3”  } }

³ Supported encryption types: SHA-256 SSE and None
⁴ PutObject permission is optional for uploading a verification file

Verification

File name	Verification file will be uploaded by PerimeterX for each processed file and it will have the same name with a suffix of _summary
Success	{ success: true, message: “ok” }
Partial success	{ success: true, message: “see errors section for more details”, errors: [“request at index - ”] }
Invalid MD5	{ success: false, message: “see errors section for more details”, errors: [“invalid body stream“] }
Request fields are missing or values invalid	{ success: false, message: “see errors section for more details”, errors: [“request at index - unexpected format: ‘’ parameter is missing or has invalid value in request body“] }
File too large	{ success: false, message: “see errors section for more details”, errors: [“payload too large, expecting max 100 MB“] }
Server error	{ success: false, message: “see errors section for more details”, errors: [“request at index - unexpected error“] }