Create Verification Session

curl --request POST \
  --url https://api.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session"

headers = {"X-API-Key": "<api-key>"}

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

print(response.text)

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session', 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.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$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.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session"

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

	req.Header.Add("X-API-Key", "<api-key>")

	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.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'

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

{
  "object": "verification_session",
  "id": "3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
  "associated_person_id": "aap_8rty2c1x7k2m9p4q1w8e5r3t",
  "status": "pending",
  "hosted_url": "https://verify.platform.example/s/3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
  "expires_at": "2026-06-19T12:00:00Z",
  "created": "2026-06-12T09:32:00Z",
  "updated": null,
  "created_by": "ak_x7k2m9p4q1w8e5r3t6y0u2i4",
  "updated_by": null
}

POST

ads

customers

{customer_id}

accounts

{account_id}

associated-persons

{ap_id}

verification-session

Create Verification Session

curl --request POST \
  --url https://api.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session"

headers = {"X-API-Key": "<api-key>"}

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

print(response.text)

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session', 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.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$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.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session"

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

	req.Header.Add("X-API-Key", "<api-key>")

	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.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hopnow.io/ads/v1/customers/{customer_id}/accounts/{account_id}/associated-persons/{ap_id}/verification-session")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'

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

{
  "object": "verification_session",
  "id": "3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
  "associated_person_id": "aap_8rty2c1x7k2m9p4q1w8e5r3t",
  "status": "pending",
  "hosted_url": "https://verify.platform.example/s/3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
  "expires_at": "2026-06-19T12:00:00Z",
  "created": "2026-06-12T09:32:00Z",
  "updated": null,
  "created_by": "ak_x7k2m9p4q1w8e5r3t6y0u2i4",
  "updated_by": null
}

Creates a hosted verification session for the associated person and returns a link to share with them (by email or redirect). The person opens the hosted page and uploads their identity documents and completes the liveness (biometric) check there; identity documents for an individual are not uploaded through this API. Hosted capture should accept passports for all countries, and Singapore NRIC for Singapore individuals. If an active (non-expired, non-terminal) session already exists, that session is returned instead of creating a new one, so the call is safe to repeat. There is no request body. Fails with 422 when the account’s kyc_status is terminal, or when the person is already approved. A rejected person may be re-verified: calling this endpoint mints a fresh session and moves their verification_status back to under_review. Identity verification of the person completes once they finish document capture and the liveness check inside the session and its status is passed; progress surfaces through the person’s verification_status, the account-level requirements block, and the account.updated webhook.

Path Parameters

string

required

Id of the Platform customer.

string

required

Id of the parent account.

string

required

Id of the associated person (e.g. aap_…).

Response

Returns 200 with the verification-session object. status is one of pending, passed, failed, expired.

Treat hosted_url as an opaque, short-lived link — the hosting domain may change and the URL must not be stored long-term or embedded in an iframe.

string

Always "verification_session".

string

Id of the verification session.

string

Id of the associated person the session verifies (e.g. aap_…).

enum

One of pending, passed, failed, expired.

string

Link to the hosted verification page to share with the person. Opaque and short-lived — do not store long-term or embed in an iframe.

string

ISO 8601 timestamp when the session expires.

string

ISO 8601 timestamp when created.

string | null

ISO 8601 timestamp when last updated.

string

Id of the API key that created the session.

string | null

Id of the API key that last updated the session.

{
  "object": "verification_session",
  "id": "3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
  "associated_person_id": "aap_8rty2c1x7k2m9p4q1w8e5r3t",
  "status": "pending",
  "hosted_url": "https://verify.platform.example/s/3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
  "expires_at": "2026-06-19T12:00:00Z",
  "created": "2026-06-12T09:32:00Z",
  "updated": null,
  "created_by": "ak_x7k2m9p4q1w8e5r3t6y0u2i4",
  "updated_by": null
}

Update Associated Person Upload Account Document

Getting Started

Integration Flows

Webhooks

Endpoints

Create Verification Session

Path Parameters

Response

​Path Parameters

​Response

Path Parameters

Response