> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # Request signals POST https://sapi-auth_token.perimeterx.net/api/v1/trust Content-Type: application/json Send a specific request and recieve its context category, risk and trust labels, and additional identifiers. You can use this information to inform your business decisions and proactively mitigate fraudulent activity. Reference: https://docs.humansecurity.com/applications/reference/request-signals ## Authentication - `Authorization` header (bearer token, required) — Authenticate with a HUMAN authentication token. ## Request ### Body (application/json) This endpoint expects a trustRequest. - `request` (TrustRequestRequest, required) — Contains request details, including the IP address, headers, and full URI. - `additional` (TrustRequestAdditional, required) — Container for custom parameters and request categorization. - `vid` (string, optional) — The Visitor ID extracted from the HUMAN cookie. - `client_uuid` (string, optional) — A unique identifier for the client session. ## Response ### 200 Returns a response with risk categories, labels, and context according to your requested [`request_category`](#request.body.additional.request_category). See [Response Categories, Reasons, & Identifiers Index](/applications/reference/response-categories-reasons-identifiers-index) for more details about each category and their associated risk labels. - `request` (map from string to requestIdentifier, optional) — Object whose keys are request IDs and whose values are request context objects. Request has no identifier `type`. - `session` (map from string to sessionIdentifier, optional) — Object whose keys are session IDs and whose values are session ID objects. The ID format is determined by the [type](#session.body.properties.type). See [Context Categories](/applications/reference/response-categories-reasons-identifiers-index#context-categories) for all possible identifier types. - `device` (map from string to deviceIdentifier, optional) — Object whose keys are device IDs and whose values are device ID objects. The ID format is determined by the [type](#device.body.properties.type). See [Context Categories](/applications/reference/response-categories-reasons-identifiers-index#context-categories) for all possible identifier types. - `network` (map from string to networkIdentifier, optional) — Object whose keys are network IDs and whose values are network ID objects. The ID format is determined by the [type](#network.body.properties.type). See [Context Categories](/applications/reference/response-categories-reasons-identifiers-index#context-categories) for all possible identifier types. - `account` (map from string to accountIdentifier, optional) — Object whose keys are account IDs and whose values are account ID objects. The ID format is determined by the [type](#account.body.properties.type). See [Context Categories](/applications/reference/response-categories-reasons-identifiers-index#context-categories) for all possible identifier types. ## Types ### TrustRequestRequest Contains request details, including the IP address, headers, and full URI. - `ip` (string, required) — The request's socket IP. - `headers` (list of TrustRequestRequestHeadersItems, required) - `url` (string, required) — The full URI of the request. ### TrustRequestAdditional Container for custom parameters and request categorization. - `request_category` (enum, required) — The context categories that to return in the response. Specify certain categories or use `*` to return all categories. See [Response Categories](/applications/reference/response-categories-reasons-identifiers-index) for more details about each category and their associated risk labels. - Allowed values: `*`, `request`, `session`, `device`, `network`, `account` - `custom_parameters` (map from string to string, optional) — Key-value pairs for application-specific contextual attributes (e.g., registration date, session ID, account, email). ### requestIdentifier Context for one request. This object is the value for a dynamic key (the request ID), not a sibling of `request`. Request has no identifier `type`. - `risk_score` (double, optional) — The risk score of the request. The score is a value between 0 and 1, where 0 is the lowest risk and 1 is the highest risk. - `risk_labels` (RequestIdentifierRiskLabels, optional) — The risk labels assigned to the request. Not all labels may be assigned to every request. Refer to the [Request](/applications/reference/response-categories-reasons-identifiers-index#request) reference for details about each label. ### sessionIdentifier Context for one session. This object is the value for a dynamic key (the session ID), not a sibling of `session`. The identifier type is determined by `type`. - `type` (enum, optional) - Allowed values: `vid`, `hid`, `customer_defined` - `risk_score` (double, optional) — The risk score of the session. The score is a value between 0 and 1, where 0 is the lowest risk and 1 is the highest risk. - `risk_labels` (SessionIdentifierRiskLabels, optional) — The risk labels assigned to the session. Not all labels may be assigned to every session. Refer to the [Session](/applications/reference/response-categories-reasons-identifiers-index#session) reference for details about each label. ### deviceIdentifier Context for one device. This object is the value for a dynamic key (the device ID), not a sibling of `device`. The identifier type is determined by `type`. - `type` (enum, optional) - Allowed values: `fingerprint` - `risk_score` (double, optional) — The risk score of the device. The score is a value between 0 and 1, where 0 is the lowest risk and 1 is the highest risk. - `risk_labels` (DeviceIdentifierRiskLabels, optional) — The risk labels assigned to the device. Not all labels may be assigned to every device. Refer to the [Device](/applications/reference/response-categories-reasons-identifiers-index#device) reference for details about each label. ### networkIdentifier Context for one network. This object is the value for a dynamic key (the network ID), not a sibling of `network`. The identifier type is determined by `type`. - `type` (enum, optional) - Allowed values: `ip`, `ja4` - `risk_score` (double, optional) — The risk score of the network. The score is a value between 0 and 1, where 0 is the lowest risk and 1 is the highest risk. - `risk_labels` (NetworkIdentifierRiskLabels, optional) — The risk labels assigned to the network. Not all labels may be assigned to every network. Refer to the [Network](/applications/reference/response-categories-reasons-identifiers-index#network) reference for details about each label. ### accountIdentifier Context for one account. This object is the value for a dynamic key (the account ID), not a sibling of `account`. The identifier type is determined by `type`. - `type` (enum, optional) - Allowed values: `email`, `account_id`, `password` - `risk_score` (double, optional) — The risk score of the account. The score is a value between 0 and 1, where 0 is the lowest risk and 1 is the highest risk. - `risk_labels` (AccountIdentifierRiskLabels, optional) — The risk labels assigned to the account. Not all labels may be assigned to every account. Refer to the [Account](/applications/reference/response-categories-reasons-identifiers-index#account) reference for details about each label. ### TrustRequestRequestHeadersItems - `name` (string, optional) — The request's header name. - `value` (string, optional) — The request's header value. ### RequestIdentifierRiskLabels The risk labels assigned to the request. Not all labels may be assigned to every request. Refer to the [Request](/applications/reference/response-categories-reasons-identifiers-index#request) reference for details about each label. - `signature` (list of any, optional) — A known signature or recognized traffic pattern. - `known_agent` (list of any, optional) — Traffic associated with a recognized AI/automated agent. This is not necessarily malicious. - `compromised_credential` (list of any, optional) — CIThe supplied credential is known to have appeared in a breach. ### SessionIdentifierRiskLabels The risk labels assigned to the session. Not all labels may be assigned to every session. Refer to the [Session](/applications/reference/response-categories-reasons-identifiers-index#session) reference for details about each label. - `volume` (list of SessionIdentifierRiskLabelsVolumeItems, optional) — BDAbnormally high request rate or traffic volume during a session. - `incident` (list of SessionIdentifierRiskLabelsIncidentItems, optional) — The session previously generated a BD incident or enforcement event. - `agent_behavior` (list of any, optional) — ATBehavior consistent with an autonomous or AI-driven agent. ### DeviceIdentifierRiskLabels The risk labels assigned to the device. Not all labels may be assigned to every device. Refer to the [Device](/applications/reference/response-categories-reasons-identifiers-index#device) reference for details about each label. - `malicious_cluster` (list of any, optional) — The device fingerprint is linked to other suspicious or malicious users. ### NetworkIdentifierRiskLabels The risk labels assigned to the network. Not all labels may be assigned to every network. Refer to the [Network](/applications/reference/response-categories-reasons-identifiers-index#network) reference for details about each label. - `reputation` (list of NetworkIdentifierRiskLabelsReputationItems, optional) — IP, ASN, proxy, VPN, TOR, hosting, or JA4 reputation is suspicious. ### AccountIdentifierRiskLabels The risk labels assigned to the account. Not all labels may be assigned to every account. Refer to the [Account](/applications/reference/response-categories-reasons-identifiers-index#account) reference for details about each label. - `profile_deviation` (list of any, optional) — ADCurrent device, location, or behavior deviates from the account's historical profile. - `velocity` (list of any, optional) — ADAbnormally rapid or frequent sensitive account activity. - `fraud_expression` (list of any, optional) — ADA configured expression matched request, enrichment, or upstream detector output. - `fake_account` (list of any, optional) — AD classified the activity as fake-account behavior. - `compromised_credential` (list of any, optional) — CIThe supplied credential is known to have appeared in a breach. ### SessionIdentifierRiskLabelsVolumeItems - `rate` (integer, optional) ### SessionIdentifierRiskLabelsIncidentItems - `time` (string, optional) — BDThe time of the incident. ### NetworkIdentifierRiskLabelsReputationItems - `residential_ip` (boolean, optional) - `malicious_ip` (boolean, optional) - `malicious_ja4` (boolean, optional) ## Examples **Request** ```json { "body": { "additional": { "custom_parameters": { "account": "3456789", "email": "user@example.com", "registration_date": "1/2/1987", "session_id": "5ed120" }, "request_category": "*" }, "client_uuid": "5ed120-699f-11e9-8a8c-51f3661ede9a", "request": { "headers": [ { "name": "User-Agent", "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" } ], "ip": "1.1.1.1", "url": "https://example.com/api/v1/login" }, "vid": "a0ca2e-699f-11e9-92f2-0242ac12000d" } } ``` **Response** ```json { "request": { "c4f8e2a1699f11e9": { "risk_score": 0.2, "risk_labels": { "signature": [], "known_agent": [] } } }, "session": { "13d1516h2_8daaf6": { "type": "vid", "risk_score": 0.2, "risk_labels": { "volume": [ { "rate": 100 } ], "incident": [ { "time": "10:00" } ] } } }, "device": { "c7f21a9b4e08d3": { "type": "fingerprint", "risk_score": 0.2, "risk_labels": { "malicious_cluster": [] } } }, "network": { "1.2.3.4": { "type": "ip", "risk_score": 0.1, "risk_labels": { "reputation": [ { "residential_ip": true, "malicious_ip": true } ] } }, "t13d1516h2_8daaf6": { "type": "ja4", "risk_score": 0.2, "risk_labels": { "reputation": [ { "malicious_ja4": true } ] } } }, "account": { "pfq342k": { "type": "password", "risk_score": 0.2, "risk_labels": { "profile_deviation": [] } }, "user@example.com": { "type": "email", "risk_score": 0.2, "risk_labels": { "fake_account": [] } } } } ``` **SDK Code** ```python import requests url = "https://sapi-auth_token.perimeterx.net/api/v1/trust" payload = { "body": { "additional": { "custom_parameters": { "account": "3456789", "email": "user@example.com", "registration_date": "1/2/1987", "session_id": "5ed120" }, "request_category": "*" }, "client_uuid": "5ed120-699f-11e9-8a8c-51f3661ede9a", "request": { "headers": [ { "name": "User-Agent", "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" } ], "ip": "1.1.1.1", "url": "https://example.com/api/v1/login" }, "vid": "a0ca2e-699f-11e9-92f2-0242ac12000d" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://sapi-auth_token.perimeterx.net/api/v1/trust'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"body":{"additional":{"custom_parameters":{"account":"3456789","email":"user@example.com","registration_date":"1/2/1987","session_id":"5ed120"},"request_category":"*"},"client_uuid":"5ed120-699f-11e9-8a8c-51f3661ede9a","request":{"headers":[{"name":"User-Agent","value":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"}],"ip":"1.1.1.1","url":"https://example.com/api/v1/login"},"vid":"a0ca2e-699f-11e9-92f2-0242ac12000d"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://sapi-auth_token.perimeterx.net/api/v1/trust" payload := strings.NewReader("{\n \"body\": {\n \"additional\": {\n \"custom_parameters\": {\n \"account\": \"3456789\",\n \"email\": \"user@example.com\",\n \"registration_date\": \"1/2/1987\",\n \"session_id\": \"5ed120\"\n },\n \"request_category\": \"*\"\n },\n \"client_uuid\": \"5ed120-699f-11e9-8a8c-51f3661ede9a\",\n \"request\": {\n \"headers\": [\n {\n \"name\": \"User-Agent\",\n \"value\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\"\n }\n ],\n \"ip\": \"1.1.1.1\",\n \"url\": \"https://example.com/api/v1/login\"\n },\n \"vid\": \"a0ca2e-699f-11e9-92f2-0242ac12000d\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://sapi-auth_token.perimeterx.net/api/v1/trust") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"body\": {\n \"additional\": {\n \"custom_parameters\": {\n \"account\": \"3456789\",\n \"email\": \"user@example.com\",\n \"registration_date\": \"1/2/1987\",\n \"session_id\": \"5ed120\"\n },\n \"request_category\": \"*\"\n },\n \"client_uuid\": \"5ed120-699f-11e9-8a8c-51f3661ede9a\",\n \"request\": {\n \"headers\": [\n {\n \"name\": \"User-Agent\",\n \"value\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\"\n }\n ],\n \"ip\": \"1.1.1.1\",\n \"url\": \"https://example.com/api/v1/login\"\n },\n \"vid\": \"a0ca2e-699f-11e9-92f2-0242ac12000d\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://sapi-auth_token.perimeterx.net/api/v1/trust") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"body\": {\n \"additional\": {\n \"custom_parameters\": {\n \"account\": \"3456789\",\n \"email\": \"user@example.com\",\n \"registration_date\": \"1/2/1987\",\n \"session_id\": \"5ed120\"\n },\n \"request_category\": \"*\"\n },\n \"client_uuid\": \"5ed120-699f-11e9-8a8c-51f3661ede9a\",\n \"request\": {\n \"headers\": [\n {\n \"name\": \"User-Agent\",\n \"value\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\"\n }\n ],\n \"ip\": \"1.1.1.1\",\n \"url\": \"https://example.com/api/v1/login\"\n },\n \"vid\": \"a0ca2e-699f-11e9-92f2-0242ac12000d\"\n }\n}") .asString(); ``` ```php request('POST', 'https://sapi-auth_token.perimeterx.net/api/v1/trust', [ 'body' => '{ "body": { "additional": { "custom_parameters": { "account": "3456789", "email": "user@example.com", "registration_date": "1/2/1987", "session_id": "5ed120" }, "request_category": "*" }, "client_uuid": "5ed120-699f-11e9-8a8c-51f3661ede9a", "request": { "headers": [ { "name": "User-Agent", "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" } ], "ip": "1.1.1.1", "url": "https://example.com/api/v1/login" }, "vid": "a0ca2e-699f-11e9-92f2-0242ac12000d" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://sapi-auth_token.perimeterx.net/api/v1/trust"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"body\": {\n \"additional\": {\n \"custom_parameters\": {\n \"account\": \"3456789\",\n \"email\": \"user@example.com\",\n \"registration_date\": \"1/2/1987\",\n \"session_id\": \"5ed120\"\n },\n \"request_category\": \"*\"\n },\n \"client_uuid\": \"5ed120-699f-11e9-8a8c-51f3661ede9a\",\n \"request\": {\n \"headers\": [\n {\n \"name\": \"User-Agent\",\n \"value\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\"\n }\n ],\n \"ip\": \"1.1.1.1\",\n \"url\": \"https://example.com/api/v1/login\"\n },\n \"vid\": \"a0ca2e-699f-11e9-92f2-0242ac12000d\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["body": [ "additional": [ "custom_parameters": [ "account": "3456789", "email": "user@example.com", "registration_date": "1/2/1987", "session_id": "5ed120" ], "request_category": "*" ], "client_uuid": "5ed120-699f-11e9-8a8c-51f3661ede9a", "request": [ "headers": [ [ "name": "User-Agent", "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" ] ], "ip": "1.1.1.1", "url": "https://example.com/api/v1/login" ], "vid": "a0ca2e-699f-11e9-92f2-0242ac12000d" ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://sapi-auth_token.perimeterx.net/api/v1/trust")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```