Applications

Start the applicant's, or a director's or shareholder's, identity verification

Starts an identity verification attempt for the application’s applicant, or with personId for a director or shareholder on it, and returns url, a hosted verification page. Send the person to it: they complete the identity check there, with no Zuba dashboard session, and land on returnUrl when given, or on a Zuba page saying the check is complete. The outcome reaches Zuba by webhook; read it back from GET /v2/applications//identity-verification, or subscribe to the application.identity_verification_updated webhook, which fires with the personId the session was started for: for the applicant, with a null personId, when they are verified or rejected (an expired attempt is rejected); for a director or shareholder, on each decision about their verification, by the provider, a reviewer or Zuba’s check of the name on the passed document, pending included when a decided session is reopened. Every director, and every shareholder at or above the ownership threshold (10% in NG, GH and KE, 25% elsewhere), must verify. The roster person marked isApplicant is the applicant: when they are one of those, starting the applicant’s session records them as a beneficial owner and their pass files its ID evidence on that record (once that start is recorded, the pass files on the marked record when they are a director or a shareholder), and personId naming them answers with the application’s own session; the mark is accepted only on a row carrying the applicant’s names, and exempts nobody else. A dashboard member with the developer role starts the applicant’s session only; personId answers 403 person_link_role for them. The link is valid until the session expires under the verification workflow’s expiry. A repeat call while the attempt is pending returns the same link, which keeps the returnUrl it was started with (for the applicant’s session, unless the verification workflow was republished in between, when a new session starts); once the attempt is rejected or expired, a call starts a new one with a new link. A new attempt replaces an earlier one, a waived outcome included, which then reads pending and no longer satisfies POST /v2/applications//submit until the attempt passes. A start is refused (409) while an attempt is still being decided by the verification provider or a reviewer, for a person already verified, and when the attempt changes while starting. A verified or waived outcome satisfies the identity requirement of POST /v2/applications//submit.

POST

applications

{id}

identity-verification

session

Start the applicant's, or a director's or shareholder's, identity verification

curl --request POST \
  --url https://api.example.com/v2/applications/{id}/identity-verification/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "personId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "returnUrl": "https://example.com/onboarding/identity-done"
}
'

import requests

url = "https://api.example.com/v2/applications/{id}/identity-verification/session"

payload = {
    "personId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "returnUrl": "https://example.com/onboarding/identity-done"
}
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({
    personId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    returnUrl: 'https://example.com/onboarding/identity-done'
  })
};

fetch('https://api.example.com/v2/applications/{id}/identity-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.example.com/v2/applications/{id}/identity-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_POSTFIELDS => json_encode([
    'personId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'returnUrl' => 'https://example.com/onboarding/identity-done'
  ]),
  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.example.com/v2/applications/{id}/identity-verification/session"

	payload := strings.NewReader("{\n  \"personId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"returnUrl\": \"https://example.com/onboarding/identity-done\"\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.example.com/v2/applications/{id}/identity-verification/session")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"personId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"returnUrl\": \"https://example.com/onboarding/identity-done\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v2/applications/{id}/identity-verification/session")

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  \"personId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"returnUrl\": \"https://example.com/onboarding/identity-done\"\n}"

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

{
  "personId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sessionId": "<string>",
  "status": "pending",
  "submittedAt": "2023-11-07T05:31:56Z",
  "url": "<string>"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Authorizations

Authorization

string

header

required

Enter Auth0 JWT token

Path Parameters

string<uuid>

required

Body

application/json

personId

string<uuid>

A director or shareholder on the application (persons on GET /v2/applications/{id}/identity-verification) to start the session for, so the link is theirs and the outcome and ID evidence file on their record. Every director, and every shareholder at or above the ownership threshold, has one; the person marked isApplicant gets the application’s own session. Omit it for the applicant.

returnUrl

string

Where the person lands after completing the hosted page: an absolute https address of yours (http://localhost is accepted outside production). Without it, the person lands on a Zuba page saying the check is complete. A session keeps the address it was started with: a repeat call while the attempt is pending returns the same link, with its original return address. The applicant’s session is the exception when the verification workflow was republished in between: a new session then starts, with this address.

Maximum string length: 2048

Example:

"https://example.com/onboarding/identity-done"

Response

personId

string<uuid> | null

required

The director or shareholder the session is for, from persons on GET /v2/applications/{id}/identity-verification; null for the application’s own session, the applicant’s.

sessionId

string | null

required

The attempt's session id. In the sandbox, where starting a session verifies the person at once, it is null for the applicant’s session and a placeholder for a director’s or shareholder’s.

status

enum<string>

required

pending until the person completes the link and the outcome arrives; read it back from GET /v2/applications/{id}/identity-verification. verified in the sandbox, where starting a session verifies the person at once.

Available options:

pending,

verified

submittedAt

string<date-time> | null

required

When the attempt reached its outcome: null while it is pending, set in the sandbox, where the attempt is verified at once.

url

string | null

required

The hosted verification page for this attempt. Send the person to it: they complete the identity check there, and the outcome reaches Zuba by webhook. Valid until the session expires under the verification workflow’s expiry. A repeat call while the attempt is pending returns it again. Null in the sandbox, where starting a session verifies the person at once.

Start the applicant's, or a director's or shareholder's, identity verification

curl --request POST \
  --url https://api.example.com/v2/applications/{id}/identity-verification/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "personId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "returnUrl": "https://example.com/onboarding/identity-done"
}
'

import requests

url = "https://api.example.com/v2/applications/{id}/identity-verification/session"

payload = {
    "personId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "returnUrl": "https://example.com/onboarding/identity-done"
}
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({
    personId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    returnUrl: 'https://example.com/onboarding/identity-done'
  })
};

fetch('https://api.example.com/v2/applications/{id}/identity-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.example.com/v2/applications/{id}/identity-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_POSTFIELDS => json_encode([
    'personId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'returnUrl' => 'https://example.com/onboarding/identity-done'
  ]),
  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.example.com/v2/applications/{id}/identity-verification/session"

	payload := strings.NewReader("{\n  \"personId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"returnUrl\": \"https://example.com/onboarding/identity-done\"\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.example.com/v2/applications/{id}/identity-verification/session")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"personId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"returnUrl\": \"https://example.com/onboarding/identity-done\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v2/applications/{id}/identity-verification/session")

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  \"personId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"returnUrl\": \"https://example.com/onboarding/identity-done\"\n}"

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

{
  "personId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sessionId": "<string>",
  "status": "pending",
  "submittedAt": "2023-11-07T05:31:56Z",
  "url": "<string>"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}