ThreatMetrix API Reference

Bind a ThreatMetrix device profile to your session ID.

The Captcha.fun ThreatMetrix API accepts kind, url, threatMetrixOrgId, threatMetrixSessionId and returns Your session ID, bound to a profile. Send the API_KEY header, create a solve with POST /v1/request, then poll GET /v2/response/{id} until ready is true.

What you’ll need

Your API key
The URL of the page where the challenge appears
threatMetrixOrgId — Your ThreatMetrix org ID: the account the profile binds to
threatMetrixSessionId — Session ID to bind the profile to. Send the same ID with the protected call
A proxy, if the result must come from your own IP (threatmetrix_proxy)

Use kind

Good to Know

Runs ThreatMetrix device profiling and binds the profile to the session ID you supply. No domain input is needed.

There’s no token to replay: after the solve, send the same session ID with your protected call.

Send the Challenge

Create Solve · POST /v1/request

Send the page details with your API key. You get a solve id back right away.

POSThttps://api.captcha.fun/v1/request

curl -X POST https://api.captcha.fun/v1/request \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "kind": "threatmetrix",
  "url": "https://your-domain.example",
  "threatMetrixOrgId": "YOUR_THREATMETRIX_ORG_ID",
  "threatMetrixSessionId": "YOUR_TRANSACTION_SESSION_ID"
}'

import requests

response = requests.post(
    "https://api.captcha.fun/v1/request",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={"kind": "threatmetrix", "url": "https://your-domain.example", "threatMetrixOrgId": "YOUR_THREATMETRIX_ORG_ID", "threatMetrixSessionId": "YOUR_TRANSACTION_SESSION_ID"},
)

print(response.status_code, response.json())

const response = await fetch("https://api.captcha.fun/v1/request", {
  method: "POST",
  headers: {
    "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
  "kind": "threatmetrix",
  "url": "https://your-domain.example",
  "threatMetrixOrgId": "YOUR_THREATMETRIX_ORG_ID",
  "threatMetrixSessionId": "YOUR_TRANSACTION_SESSION_ID"
})
});

console.log(response.status, await response.json());

Response

Returns the solve id. Use it to get the result.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Started Solving"
}

{
  "message": "invalid kind"
}

Request fields6 body fields · 4 required

Headers

Name	Type	Required	Description
API_KEY	string	Yes	Your API key
Content-Type	string	Yes	`application/json`
APP_ID	string	No	Optional app ID for request tracking

Body

Name	Type	Required	Description
kind	string	Yes	One of `threatmetrix`, `threatmetrix_proxy`
url	string	Yes	Page URL where the challenge appears
threatMetrixOrgId	string	Yes	Your ThreatMetrix org ID: the account the profile binds to
threatMetrixSessionId	string	Yes	Session ID to bind the profile to. Send the same ID with the protected call
proxy	string	No	For `_proxy` kinds: `host:port` or `host:port:username:password`
platform	string	No	Requested platform label: `windows` (default) or `mac`

Wait for the Result

Get Solve · GET /v2/response/{id}

Use the solve id to fetch the result.

GEThttps://api.captcha.fun/v2/response/{id}

Poll every second until ready is true.

GEThttps://api.captcha.fun/v1/response/{id}

Long polling: the request stays open until the solve finishes or times out. Send it once and wait.

Example

curl -X GET https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000 \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Accept": "application/json"
    }
)

print(response.status_code, response.json())

const response = await fetch(
  "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000",
  {
    method: "GET",
    headers: {
      "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "Accept": "application/json"
    }
  }
);

const data = await response.json();
console.log(response.status, data);

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000", nil)
    req.Header.Set("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
    req.Header.Set("Accept", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(resp.StatusCode, result)
}

import java.net.http.*;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000"))
            .header("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
            .header("Accept", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
client.DefaultRequestHeaders.Add("Accept", "application/json");

var response = await client.GetAsync("https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine($"{(int)response.StatusCode} {result}");

Response

{
  "ready": true,
  "status": "SUCCESS",
  "success": true,
  "userAgent": "RETURNED_USER_AGENT",
  "secUa": "RETURNED_SEC_CH_UA",
  "token": "YOUR_TRANSACTION_SESSION_ID"
}

{
  "message": "API_KEY Header Missing"
}

Example

curl -X GET https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000 \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Accept": "application/json"
    }
)

print(response.status_code, response.json())

const response = await fetch(
  "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000",
  {
    method: "GET",
    headers: {
      "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "Accept": "application/json"
    }
  }
);

const data = await response.json();
console.log(response.status, data);

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000", nil)
    req.Header.Set("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
    req.Header.Set("Accept", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(resp.StatusCode, result)
}

import java.net.http.*;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000"))
            .header("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
            .header("Accept", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
client.DefaultRequestHeaders.Add("Accept", "application/json");

var response = await client.GetAsync("https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine($"{(int)response.StatusCode} {result}");

Response

{
  "status": "SUCCESS",
  "success": true,
  "userAgent": "RETURNED_USER_AGENT",
  "secUa": "RETURNED_SEC_CH_UA",
  "token": "YOUR_TRANSACTION_SESSION_ID"
}

{
  "message": "API_KEY Header Missing"
}

Request and response fields7 response fields

Request

Name	Type	Required	Description
id	string (UUID)	Yes	Path parameter. The `id` from Create Solve
API_KEY	string	Yes	Header. Your API key

Response Fields

Name	Type	Required	Description
ready	boolean	—	`true` when the solve is finished (v2 only)
status	string	—	`PENDING` while solving, then `SUCCESS` or `FAILURE`
success	boolean	—	Whether the solve succeeded
userAgent	string	—	Value to send as `User-Agent` when using the result. Preserve it exactly
secUa	string	—	Value to send as `Sec-CH-UA` when using the result
token	string	—	Your session ID, echoed once the profile is bound
message	string	—	Failure reason. Omitted on success

Replay the Request

Your session ID, bound to a profile

Send the same session ID with the protected login or payment call. ThreatMetrix scores it against the profile bound during the solve.
The profile is bound to the solving browser's fingerprint and egress IP — send the protected call from the same egress. Profiles accumulate trust server-side; a session id solved seconds ago starts with minimal history.

When using a successful result, preserve the returned userAgent as User-Agent and secUa as Sec-CH-UA.

Wrong or rejected result? Report the failed solve.