Get a detection

curl --request GET \
  --url https://api.example.com/v1/detection/{detection_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/detection/{detection_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/detection/{detection_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/detection/{detection_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/detection/{detection_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "QUEUED",
  "score": 123,
  "billable": true,
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "submitted_by": "<string>",
  "batch_id": "<string>",
  "filename": "<string>",
  "content_type": "<string>",
  "size_bytes": 123,
  "s3_key": "<string>",
  "failure_message": "<string>",
  "failure_code": "<string>",
  "discovered": [
    "<string>"
  ],
  "authoritative": {
    "check_id": "<string>",
    "trust": "<string>",
    "directive": "<string>"
  },
  "verdict": {
    "fraud_score": 123,
    "document_type_match": true,
    "actual_doc_type": "<string>",
    "reasoning": "<string>",
    "per_check": [
      {
        "check_id": "<string>",
        "importance": 123,
        "reasoning": "<string>"
      }
    ]
  },
  "agent_error": "<string>",
  "agent_run_id": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Detections

Get a detection

Read one detection and its result.

Poll this operation until status is COMPLETED or FAILED. The status field always shows the durable record. The verdict field comes from the workflow history, which expires after the retention period, so an old COMPLETED detection can have verdict: null.

score is null when one check determined the document verification result alone. The authoritative object then carries the document check finding.

A FAILED detection gives the reason in failure_code and failure_message.

Scope: DocumentVerification:detections:get

GET

detection

{detection_id}

Get a detection

curl --request GET \
  --url https://api.example.com/v1/detection/{detection_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/detection/{detection_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/detection/{detection_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/detection/{detection_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/detection/{detection_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "QUEUED",
  "score": 123,
  "billable": true,
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "submitted_by": "<string>",
  "batch_id": "<string>",
  "filename": "<string>",
  "content_type": "<string>",
  "size_bytes": 123,
  "s3_key": "<string>",
  "failure_message": "<string>",
  "failure_code": "<string>",
  "discovered": [
    "<string>"
  ],
  "authoritative": {
    "check_id": "<string>",
    "trust": "<string>",
    "directive": "<string>"
  },
  "verdict": {
    "fraud_score": 123,
    "document_type_match": true,
    "actual_doc_type": "<string>",
    "reasoning": "<string>",
    "per_check": [
      {
        "check_id": "<string>",
        "importance": 123,
        "reasoning": "<string>"
      }
    ]
  },
  "agent_error": "<string>",
  "agent_run_id": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

detection_id

string

required

Response

The detection record, with the verdict if it exists.

The durable record plus, once completed, the workflow result.

string

required

status

enum<string>

required

QUEUED, RUNNING, COMPLETED, or FAILED.

Available options:

QUEUED,

RUNNING,

COMPLETED,

FAILED

score

integer | null

required

The fraud score, normally 0 to 100. A higher score means a higher likelihood of fraud, but does not guarantee fraud. Humans should always review high-risk cases. Null while the detection runs, and null when one check determined the document verification result alone.

billable

boolean

required

created_at

string<date-time>

required

completed_at

string<date-time> | null

required

submitted_by

string | null

required

batch_id

string | null

required

The batch that holds this detection, if one exists.

filename

string | null

required

content_type

string | null

required

size_bytes

integer | null

required

s3_key

string | null

required

Where the API keeps the document.

failure_message

string | null

required

A sentence that explains failure_code.

failure_code

string | null

The reason for a FAILED status. Null in all other states.

discovered

string[] | null

Facts that the pipeline found in the document, such as qr_present.

authoritative

AuthoritativeResult · object | null

Set if one check determined the document verification result alone. The agent does not run in that case, so verdict and score are both null.

Show child attributes

verdict

VerdictResult · object | null

The result of the analysis. Null while the detection runs, and null again after the workflow history expires.

Show child attributes

agent_error

string | null

Why the analysis agent failed.

agent_run_id

string | null

The agent run, for support requests.

Getting started

API reference

Get a detection

Authorizations

Path Parameters

Response