Truth Data API

To automatically send Truth Data to Arkose, please follow the steps below:

Step 1: Create a Client ID and Client Secret pair via Arkose Command Center. You can do this by navigating to the sidebar > Tokens > Create Token. Add a description for your use. This is a one-time action and the same ID and secret can be used by all the keys under your account.

Step 2: Generate an authorization token for the client ID and secret by calling https://client-api.arkoselabs.com/truth_data_api/v1/authorize.

Request Body:

{
  "client_id": "",
  "client_secret": ""
}

This method then verifies and authenticates the client id and secret via Auth0. Auth0 creates an access token that is valid for 24 hours. You need to get an authorization token every 24 hours by implementing checks that monitor the "expires_in" value to avoid unnecessary token creation on every request.

{
    "access_token": "<token>"
    "token_type": "Bearer",
    "expires_in": 86400
}

Step 3: Use the token received to invoke Arkose Labs Truth Data API. API URL: https://client-api.arkoselabs.com/truth_data_api/v1/stream_data

The request body needs to be as the following:

Request Header:
{
   Authorization: [Bearer <token>]
}
Request Body:
{
   "arkose_session_id": "32560e3747191b697.1304102202", // mandatory
   "public_key": "D6A0C8E8-F7E7-4A39-A515-5BE578369101", // mandatory
   "session_create_timestamp": "2021-10-30 12:31:29", // optional
   "decision_timestamp": "2021-10-30 12:31:30", // optional
   "is_legit": 0, // mandatory
   "event_type": 2, // optional
   "fraud_category": 3, // optional
   "fraud_type": 2 // optional
}

📘
Please let your Customer Success Manager know if you can't view the API Access section in Arkose Command Center.

Truth Data API Fields

For the optional fields that accept string enums, Arkose improves our analysis by doing a strict validation against the defined enums. Please contact us if you want an additional enum added to the list.

Field	Mandatory/Optional	Description	Format
`arkose_session_id`	Mandatory	A primary link between the truth data and its Arkose session.	`11663602dda317f65.6750167505`
`public_key`	Mandatory	Public key against which the session was originally generated. *Sending a wrong public key will significantly impact Arkose Labs' ability to process these truth data sessions correctly.	`1F662B05-B798-D2A3-B687-C1D43DD4EB76`
`session_create_time`	Optional	The date and timestamp when the customer created the session.	`YYYY-MM-DD HH:MM:SS`
`decision_time`	Optional	The date and timestamp when the customer decided if the session was good or bad.	`YYYY-MM-DD HH:MM:SS`
`is_legit`	Mandatory	A high level overview of whether the customer considers the session legit or non-legit.	`0` (indicates non-legit) `1` (indicates legit)
`event_type`	Optional	Stage of a user’s lifecycle where the event occurred. This data helps Arkose create appropriate algorithms tailored to the specific event type, thus reducing false positives.	`1` (registration) `2` (login) `3` (password_reset) `4` (account_settings) `5` (transaction)
`fraud_category`	Optional	The overarching category that the fraud falls in. This information helps Arkose tune the appropriate algorithm’s parameters, thus reducing false positives.	`1` (automation) `2`(fraud_farm) `3` (human_driven)
`fraud_type`	Optional	A granular view of the committed fraud. This helps Arkose create and improve algorithms tailored to specific fraud type and/or verticals, improving our overall accuracy.	`1` (fake_email) `2` (fake_phone_number) `3` (stolen_financial_instrument) `4` (fraudulent_chargeback) `5` (social_engineering_attempt)

Sending Batch Data Via the Truth Data API

To send batch requests, follow the steps:

Step 1: Create a Client ID and Client Secret pair via Arkose Command Center. You can do this by navigating to the sidebar > Tokens > Create Token. Add a description for your use. This is a one-time action and the same ID and Secret can be used by all the keys under your account.

Step 2: Generate an authorization token for the client ID and secret by calling https://client-api.arkoselabs.com/truth_data_api/v1/authorize.

Request Body:

{
  "client_id": "",
  "client_secret": ""
}

This method then verifies and authenticates the client id and secret via Auth0. Auth0 creates an access token that is valid for 24 hours. You need to get an authorization token every 24 hours by implementing checks that monitor the expires_in value to avoid unnecessary token creation on every request.

{
    "access_token": "<token>"
    "token_type": "Bearer",
    "expires_in": 86400
}

Step 3: Use the token received to invoke the Arkose Labs Truth Data API. API URL: https://client-api.arkoselabs.com/truth_data_api/v1/batch_data

The request body needs to be as the following:

Request Header:
{
   Authorization: [Bearer <token>]
}
Request Body:
{"sessions": [{
   "arkose_session_id": "32560e3747191b697.1304102202", // mandatory
   "public_key": "D6A0C8E8-F7E7-4A39-A515-5BE578369101", // mandatory
   "session_create_timestamp": "2021-10-30 12:31:29", // optional
   "decision_timestamp": "2021-10-30 12:31:30", // optional
   "is_legit": 0, // mandatory
   "event_type": 2, // optional
   "fraud_category": 3, // optional
   "fraud_type": 2 // optional,
}, {
  "arkose_session_id": "42560e3747191b697.1304102202",
  "public_key": "07EAB4B8-2D80-4234-B897-A2CD1F194866",
  "session_create_timestamp": "2025-05-10 12:31:29",
  "decision_timestamp": "2025-05-10 12:31:30",
  "is_legit": 2,
  "event_type": 1
}]}

Note: 500 session limit per 1 batch request

Sample Batch Response:

200: Call Succeeded
400: Bad Request
401: Unauthorized
500: Internal Service Error
501: The server does not support the functionality required to fulfill the request