Feedback Loop API

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

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

NameTypeRequiredValuesDescription
id_typeStringV“vid”/ “custom_id”`VID - PerimeterX unique visitor ID (as provided by PerimeterX).
id_valueStringVThe VID / Custom_id value
app_idStringVPerimeterX application ID
timestampepochVEpoch in milliseconds
is_user_maliciousBooleanVtrue / false
additional_dataObjectOptionalJSON object in the format of {key1: value1, key2: value2, ….} 2

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” 
     }
}]

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

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

NameTypeRequiredValuesDescription
id_typeStringV“vid”/ “custom_id”`VID - PerimeterX unique visitor ID (as provided by PerimeterX).
id_valueStringVThe VID / Custom_id value
app_idStringVPerimeterX application ID
timestampepochVEpoch in milliseconds
is_user_maliciousBooleanVtrue / false
additional_dataObjectOptionalJSON 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”  } }

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“]
}


Did this page help you?