Enforce an HTTP request | HUMAN Documentation

Processes an HTTP request and returns an enforcement response.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

requestobjectRequired

The HTTP request that should be enforced.

additionalobjectOptional

Any additional data to consider while processing the HTTP request.

Response

success

statusenum or null

Whether the Enforce API call was successful. 0 for success, -1 for failure.

Allowed values:

scoredouble or null0-100

The risk score associated with the request on a scale of 0-100, where 0 is not a bot and 100 is a bot.

actionenum or null

The type of block response that should be returned to the end user. See Possible values:

c: Captcha. See HUMAN Challenge for details.
b: Hard block. See Create custom Traffic policy rules for details.
r: Rate limit. See Traffic policy settings for details.
a: Allow.

The type of block response that should be returned to the end user. See Possible values: - `c`: Captcha. See [HUMAN Challenge](/applications/create-a-human-challenge) for details. - `b`: Hard block. See [Create custom Traffic policy rules](/applications/create-custom-traffic-policy-rules) for details. - `r`: Rate limit. See [Traffic policy settings](/applications/traffic-policy-settings#rate-limiting-rules) for details. - `a`: Allow.

Allowed values:

pxhdstring or null

A hashed data value that should be set on the returned response as the _pxhd cookie

uuidstring or null

The unique ID associated with the web interaction this request was a part of.

vidstring or null

The unique ID associated with the user who sent the request if known.

data_enrichmentobject or null

A data enrichment object with additioanl information about the detection that was performed on the request. See Data classification enrichment for details. In the scope of the integration, the most relevant fields are:

cgp: Holds a value of 1 once a Challenge is successfully solved for the configured grace period. This defaults to 15 minutes and can be changed upon request. If a challenge is not solved, if the grace period passes, or if the request was reidentified as a bot (such as going above the request volume threshold), the cgp flag will be empty or have a value of 0. If the request was reidentified as a bot, the score and action will also be updated accordingly.
bm: Holds a value of 1 if the request is in bypass mode. If the traffic is not in bypass mode, the field won’t be a part of the data enrichment. Therefore, either bm: 1 appears if bypass mode is enabled, or it will not appear at all.

A data enrichment object with additioanl information about the detection that was performed on the request. See [Data classification enrichment](/applications/data-classification-enrichment#available-enrichment-data-by-type) for details. In the scope of the integration, the most relevant fields are: - `cgp`: Holds a value of 1 once a Challenge is successfully solved for the configured grace period. This defaults to 15 minutes and can be changed upon request. If a challenge is not solved, if the grace period passes, or if the request was reidentified as a bot (such as going above the request volume threshold), the `cgp` flag will be empty or have a value of 0. If the request was reidentified as a bot, the score and action will also be updated accordingly. - `bm`: Holds a value of 1 if the request is in bypass mode. If the traffic is not in bypass mode, the field won't be a part of the data enrichment. Therefore, either `bm: 1` appears if bypass mode is enabled, or it will not appear at all.

Errors

cgp: Holds a value of 1 once a Challenge is successfully solved for the configured grace period. This defaults to 15 minutes and can be changed upon request. If a challenge is not solved, if the grace period passes, or if the request was reidentified as a bot (such as going above the request volume threshold), the cgp flag will be empty or have a value of 0. If the request was reidentified as a bot, the score and action will also be updated accordingly.
bm: Holds a value of 1 if the request is in bypass mode. If the traffic is not in bypass mode, the field won’t be a part of the data enrichment. Therefore, either bm: 1 appears if bypass mode is enabled, or it will not appear at all.

1	import requests
2
3	url = "https://https://sapi-123456789.perimeterx.net/api/v1/enforce/risk"
4
5	payload = { "request": {
6	"url": "https://www.example.com/path?query=string",
7	"client_ip": "1.2.3.4",
8	"method": "POST",
9	"headers": [
10	{
11	"name": "User-Agent",
12	"value": "TestUserAgent"
13	},
14	{
15	"name": "Content-Type",
16	"value": "application/json"
17	},
18	{
19	"name": "Content-Length",
20	"value": "129"
21	}
22	]
23	} }
24	headers = {
25	"Authorization": "Bearer <token>",
26	"Content-Type": "application/json"
27	}
28
29	response = requests.post(url, json=payload, headers=headers)
30
31	print(response.json())

1	{
2	"status": 0,
3	"score": 100,
4	"action": "c",
5	"pxhd": "0000000000000000000000000000000000000000000000000000000000000000:00000000-0000-0000-0000-000000000000",
6	"uuid": "00000000-0000-0000-0000-000000000000",
7	"vid": "00000000-0000-0000-0000-000000000000",
8	"data_enrichment": {
9	"timestamp": "1729724240012",
10	"f_type": "b",
11	"f_id": "00000000-0000-0000-0000-000000000000",
12	"f_origin": "custom",
13	"f_kb": 0,
14	"ipc_id": [],
15	"inc_id": [
16	"00000000000000000000000000000000"
17	]
18	}
19	}