In-person verifications

Create In-person Verification

Send a digital ID verification to a reader terminal. The reader asks the customer to choose what to share, then the customer taps their phone or presents a QR code for the reader to scan.

The response doesn’t include the result. Poll Get an in-person verification with the returned verificationId for it.

A reader handles one verification at a time. The reader’s action must start with a digital credential request step with the Proximity transport enabled.

If the request fails or times out, retry it with the same terminalId and reference. While that verification is in progress, the retry returns it instead of starting a new one. Once it has finished, the same request starts a new verification.

POST

terminal

proximity-verifications

Create an in-person verification

curl --request POST \
  --url https://api.authsignal.com/v1/terminal/proximity-verifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "terminalId": "<string>",
  "reference": "<string>"
}
'

import requests

url = "https://api.authsignal.com/v1/terminal/proximity-verifications"

payload = {
    "terminalId": "<string>",
    "reference": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({terminalId: '<string>', reference: '<string>'})
};

fetch('https://api.authsignal.com/v1/terminal/proximity-verifications', 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.authsignal.com/v1/terminal/proximity-verifications",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'terminalId' => '<string>',
    'reference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.authsignal.com/v1/terminal/proximity-verifications"

	payload := strings.NewReader("{\n  \"terminalId\": \"<string>\",\n  \"reference\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.authsignal.com/v1/terminal/proximity-verifications")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"terminalId\": \"<string>\",\n  \"reference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.authsignal.com/v1/terminal/proximity-verifications")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"terminalId\": \"<string>\",\n  \"reference\": \"<string>\"\n}"

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

{
  "verificationId": "41feec4e-5a9e-46bd-9068-72261a57fc5d",
  "terminalId": "8c2d0e1b-5f4a-4c3e-9b8a-7d6c5b4a3f2e",
  "optionId": null,
  "optionName": null,
  "reference": "sale-1042",
  "status": "PENDING",
  "createdAt": "2026-10-15T01:02:03.000Z",
  "expiresAt": "2026-10-15T01:07:03.000Z",
  "resultExpiresAt": "2026-10-15T01:12:03.000Z"
}

{
  "error": "terminal_busy",
  "errorCode": "terminal_busy",
  "errorDescription": ""
}

{
  "error": "terminal_busy",
  "errorCode": "terminal_busy",
  "errorDescription": ""
}

{
  "error": "terminal_busy",
  "errorCode": "terminal_busy",
  "errorDescription": ""
}

{
  "error": "terminal_busy",
  "errorCode": "terminal_busy",
  "errorDescription": ""
}

Authorizations

Authorization

string

header

required

Use the controller token issued for your point of sale device. Contact Authsignal to issue a controller token.

Body

application/json

terminalId

string

required

The ID of the reader terminal to send the verification to. The reader shows its terminal ID as a QR code in its settings.

Maximum string length: 100

reference

string

A reference identifier originating from the point of sale system, such as a sale ID. Use a new reference for each sale.

Maximum string length: 200

Response

Accepted

verificationId

string

required

The ID of the in-person verification.

terminalId

string

required

The ID of the reader terminal the verification was sent to.

optionId

string | null

required

The request option the customer chose on the reader. null until they choose.

optionName

string | null

required

The display name of the chosen request option. null until the customer chooses.

status

enum<string>

required

PENDING for a new verification. A retry for the same sale returns the verification with its current status.

Available options:

PENDING,

IN_PROGRESS,

VERIFYING

createdAt

string<date-time>

required

expiresAt

string<date-time>

required

When the customer must have presented their credential by.

resultExpiresAt

string<date-time>

required

When the verification and its result stop being available.

reference

string

A reference identifier originating from the point of sale system.

⌘I

Create an in-person verification

curl --request POST \
  --url https://api.authsignal.com/v1/terminal/proximity-verifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "terminalId": "<string>",
  "reference": "<string>"
}
'

import requests

url = "https://api.authsignal.com/v1/terminal/proximity-verifications"

payload = {
    "terminalId": "<string>",
    "reference": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({terminalId: '<string>', reference: '<string>'})
};

fetch('https://api.authsignal.com/v1/terminal/proximity-verifications', 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.authsignal.com/v1/terminal/proximity-verifications",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'terminalId' => '<string>',
    'reference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.authsignal.com/v1/terminal/proximity-verifications"

	payload := strings.NewReader("{\n  \"terminalId\": \"<string>\",\n  \"reference\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.authsignal.com/v1/terminal/proximity-verifications")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"terminalId\": \"<string>\",\n  \"reference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.authsignal.com/v1/terminal/proximity-verifications")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"terminalId\": \"<string>\",\n  \"reference\": \"<string>\"\n}"

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

{
  "verificationId": "41feec4e-5a9e-46bd-9068-72261a57fc5d",
  "terminalId": "8c2d0e1b-5f4a-4c3e-9b8a-7d6c5b4a3f2e",
  "optionId": null,
  "optionName": null,
  "reference": "sale-1042",
  "status": "PENDING",
  "createdAt": "2026-10-15T01:02:03.000Z",
  "expiresAt": "2026-10-15T01:07:03.000Z",
  "resultExpiresAt": "2026-10-15T01:12:03.000Z"
}

{
  "error": "terminal_busy",
  "errorCode": "terminal_busy",
  "errorDescription": ""
}

{
  "error": "terminal_busy",
  "errorCode": "terminal_busy",
  "errorDescription": ""
}

{
  "error": "terminal_busy",
  "errorCode": "terminal_busy",
  "errorDescription": ""
}

{
  "error": "terminal_busy",
  "errorCode": "terminal_busy",
  "errorDescription": ""
}

API reference

Server API

Client API

Management API

Call Connect API

Terminal API

Create In-person Verification

Authorizations

Body

Response