Request signals | HUMAN Documentation

curl -X POST https://sapi-auth_token.perimeterx.net/api/v1/trust \
     -H "Authorization: Bearer <px_auth_token>" \
     -H "Content-Type: application/json" \
     -d '{
  "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"
  }
}'

{
  "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": []
      }
    }
  }
}

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.

Authentication

AuthorizationBearer

Authenticate with a HUMAN authentication token.

Request

This endpoint expects an object.

requestobjectRequired

Contains request details, including the IP address, headers, and full URI.

additionalobjectRequired

Container for custom parameters and request categorization.

vidstringOptional

The Visitor ID extracted from the HUMAN cookie.

client_uuidstringOptional

A unique identifier for the client session.

Response

Returns a response with risk categories, labels, and context according to your requested request_category. See Response Categories, Reasons, & Identifiers Index for more details about each category and their associated risk labels.

requestmap from strings to objectsOptional

Object whose keys are request IDs and whose values are request context objects. Request has no identifier type.

sessionmap from strings to objectsOptional

Object whose keys are session IDs and whose values are session ID objects. The ID format is determined by the type. See Context Categories for all possible identifier types.

devicemap from strings to objectsOptional

Object whose keys are device IDs and whose values are device ID objects. The ID format is determined by the type. See Context Categories for all possible identifier types.

networkmap from strings to objectsOptional

Object whose keys are network IDs and whose values are network ID objects. The ID format is determined by the type. See Context Categories for all possible identifier types.

accountmap from strings to objectsOptional

Object whose keys are account IDs and whose values are account ID objects. The ID format is determined by the type. See Context Categories for all possible identifier types.