Calling Verify API

Requests to the Verify API can either be sent via:

  • An application/json body (POST)

  • A URL with query parameters (GET)

  • An HTTP header.

POST and GET Request Parameters

This table shows the parameters that should be included within the GET or POST requests.

Information on the current Verify API request and response schema is in the documentation at Verify Request and Response Schemas. The source information for it is at the following URLs. Please substitute your own customized URL for the descriptions and examples used in this document.

  • Verify request schema:
    <company>-verify.arkoselabs.com/api/v4/verify/schema/request

  • Verify response schema:
    <company>-verify.arkoselabs.com/api/v4/verify/schema/response

e.g.
https://acme-verify.arkoselabs.com/api/v4/verify/schema/request
https://acme-verify.arkoselabs.com/api/v4/verify/schema/response

Here is an example of how to get the response schema using cURL:

curl https://<company>-verify.arkoselabs.com/api/v4/verify/schema/request

The generic URLs will continue working until all customers are using their personalized URLs; e.g.

  • http://verify.arkoselabs.com/api/v4/verify/schema/request
  • http://verify.arkoselabs.com/api/v4/verify/schema/response
Parameter NameRequired / OptionalDescription
private_keyRequiredThe private key issued by Arkose Labs along with the public key used for the client-side API.
session_tokenRequiredThe token value contained within the token key of the client-side API response object. This object is provided within the client-side onComplete callback.
log_dataOptionalA freeform string that allows information to be passed to the Verify API. This can be used to pass basic information that you want stored by Arkose with the session data. This can be used internally by Arkose when performing manual traffic analysis.

GET request

Below is an example URL that includes the parameters from the above table as query parameters. Before actually using it, replace the ??? placeholders with the real values to be used, as well as replacing <company> with your company's personalized API URL name.

https://<company>-verify.arkoselabs.com/api/v4/verify/?private_key=???&session_token=???&log_data=???

POST request

The POST request requires the use of the request body. Below is an example of a JSON request body using the parameters from the table above. Note that you can send the email_address field only via POST requests.

πŸ‘

Arkose Email Intelligence Available As An Add-On Feature

Email Intelligence, which involves assessing the risk based on the email address, is an add-on feature to both Arkose Detect & Arkose Protect. For more information, see the Knowledge Base (support login required) here and here.

Talk to your account rep to check if you qualify for a free trial.

{
  "private_key" : "_PRIVATE_KEY_HERE_",
  "session_token" : "_SESSION_TOKEN_HERE_",
  "log_data" : "_LOG_DATA_HERE_",
  "email_address" : "_EMAIL_ADDRESS_HERE_"
}

HTTP Header Request

πŸ“˜

Requests using HTTP headers do not support log_data

In the instructions above, the private key and session token are passed via the URL query parameters (GET) or POST body. An alternative method of passing the private key and session token to the Verify API is via HTTP headers on the request. The table below shows the name of the headers that should be used.

Parameter NameRequired / OptionalDescription
Arkose-Private-KeyRequiredThis is the private key issued by Arkose Labs along with the public key used for the client-side API
Arkose-Session-TokenRequiredThis is the token value contained within the token key of the client-side API response object. This object is provided within the client-side onComplete callback

Here is an example of providing the required data using the headers listed above in a simple Curl command.

curl -H "Content-Type: application/json" -H "Arkose-Private-Key: <your private key>" -H "Arkose-Session-Token: <value of verification-token>" https://<company>-verify.arkoselabs.com/api/v4/verify/