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
Accept
application/json
Content-Type
application/json
Authorization
Bearer 1
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, ….} 2
1 This is different from the enforcer token, and is sent separately. Each token is associated to only one app_id 2 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
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 type3
Access
Provide PerimeterX with the following permissions for the bucket:
ListBucket
GetObject
PutObject4
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, ….}
3 Supported encryption types: SHA-256 SSE and None 4 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“]
}