Verify Customer - Adhere by Smartcomply

Verify Customer

curl --request POST \
  --url https://adhere-api.smartcomply.com/api/onboarding/verify_customer \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "country": "nigeria",
  "identifier": "12345678901",
  "identifier_type": "bvn"
}
'

import requests

url = "https://adhere-api.smartcomply.com/api/onboarding/verify_customer"

payload = {
    "country": "nigeria",
    "identifier": "12345678901",
    "identifier_type": "bvn"
}
headers = {
    "x-access-token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-access-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({country: 'nigeria', identifier: '12345678901', identifier_type: 'bvn'})
};

fetch('https://adhere-api.smartcomply.com/api/onboarding/verify_customer', 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://adhere-api.smartcomply.com/api/onboarding/verify_customer",
  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([
    'country' => 'nigeria',
    'identifier' => '12345678901',
    'identifier_type' => 'bvn'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-access-token: <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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://adhere-api.smartcomply.com/api/onboarding/verify_customer"

	payload := strings.NewReader("{\n  \"country\": \"nigeria\",\n  \"identifier\": \"12345678901\",\n  \"identifier_type\": \"bvn\"\n}")

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

	req.Header.Add("x-access-token", "<api-key>")
	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://adhere-api.smartcomply.com/api/onboarding/verify_customer")
  .header("x-access-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"nigeria\",\n  \"identifier\": \"12345678901\",\n  \"identifier_type\": \"bvn\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://adhere-api.smartcomply.com/api/onboarding/verify_customer")

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

request = Net::HTTP::Post.new(url)
request["x-access-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country\": \"nigeria\",\n  \"identifier\": \"12345678901\",\n  \"identifier_type\": \"bvn\"\n}"

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

{
  "status": "failed",
  "data": [
    "<unknown>"
  ],
  "message": "<string>"
}

{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}

POST

api

onboarding

verify_customer

Verify Customer

curl --request POST \
  --url https://adhere-api.smartcomply.com/api/onboarding/verify_customer \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "country": "nigeria",
  "identifier": "12345678901",
  "identifier_type": "bvn"
}
'

import requests

url = "https://adhere-api.smartcomply.com/api/onboarding/verify_customer"

payload = {
    "country": "nigeria",
    "identifier": "12345678901",
    "identifier_type": "bvn"
}
headers = {
    "x-access-token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-access-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({country: 'nigeria', identifier: '12345678901', identifier_type: 'bvn'})
};

fetch('https://adhere-api.smartcomply.com/api/onboarding/verify_customer', 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://adhere-api.smartcomply.com/api/onboarding/verify_customer",
  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([
    'country' => 'nigeria',
    'identifier' => '12345678901',
    'identifier_type' => 'bvn'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-access-token: <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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://adhere-api.smartcomply.com/api/onboarding/verify_customer"

	payload := strings.NewReader("{\n  \"country\": \"nigeria\",\n  \"identifier\": \"12345678901\",\n  \"identifier_type\": \"bvn\"\n}")

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

	req.Header.Add("x-access-token", "<api-key>")
	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://adhere-api.smartcomply.com/api/onboarding/verify_customer")
  .header("x-access-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"nigeria\",\n  \"identifier\": \"12345678901\",\n  \"identifier_type\": \"bvn\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://adhere-api.smartcomply.com/api/onboarding/verify_customer")

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

request = Net::HTTP::Post.new(url)
request["x-access-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country\": \"nigeria\",\n  \"identifier\": \"12345678901\",\n  \"identifier_type\": \"bvn\"\n}"

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

{
  "status": "failed",
  "data": [
    "<unknown>"
  ],
  "message": "<string>"
}

{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}

Endpoint

POST /api/onboarding/verify_customer

Request

Headers

Header	Value	Required
`x-access-token`	Your API key	Yes
`Content-Type`	`application/json`	Yes

Body Parameters

Parameter	Type	Required	Description
`country`	string	Yes	Country of the customer. Supported: `nigeria`, `kenya`, `ghana`, `uganda`, `rwanda`
`identifier`	string	Yes	The customer’s ID number (e.g. BVN, NIN, National ID)
`identifier_type`	string	No	Overrides the country default. See supported values

Example

curl -X POST https://adhere-api.smartcomply.com/api/onboarding/verify_customer \
  -H "x-access-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "nigeria",
    "identifier": "12345678901"
  }'

import requests

response = requests.post(
    "https://adhere-api.smartcomply.com/api/onboarding/verify_customer",
    headers={"x-access-token": "YOUR_API_KEY"},
    json={
        "country": "nigeria",
        "identifier": "12345678901",
    },
)
print(response.json())

const response = await fetch("https://adhere-api.smartcomply.com/api/onboarding/verify_customer", {
  method: "POST",
  headers: {
    "x-access-token": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country: "nigeria",
    identifier: "12345678901",
  }),
});
const data = await response.json();

Response

All responses return HTTP 200. Use the decision field — not the HTTP status — to determine the onboarding outcome. See the Decision Guide for how to act on each value.

string

Always "success" on a 200 response.

string

Always "Customer onboarding completed" on success.

object

Hide data fields

number

Unique ID for this onboarding record.

object

Result of the identity verification step.

Show identity fields

boolean

true if the identifier was successfully verified against the issuing authority.

string

The document type used, e.g. "BVN", "NIN", "National ID".

string

Present when verified: true.

string

Present when verified: true.

string

Present when verified: true and the provider returns a middle name.

string

ISO-8601 date string. Present when verified: true.

string

Present when verified: true.

string

Present when verified: true and available from the provider.

string

Error message from the verification provider. Only present when verified: false.

object

AML screening results. Always returned in a consistent shape, even when screening was skipped.

Show screening fields

array

Sanctions matches. Each entry contains entity_name, recorded_date, country, sanction_body, sanction_types, and other_information.

array

PEP matches. Each entry contains name, pep_types, gender, country, source, and political_post.

array

Currently always [] — will be enabled as a configurable step in a future release.

string

"low", "medium", or "high".

string

Present only when screening was skipped. Explains why.

string

"pass", "review", or "fail". See the Decision Guide.

Pass — identity verified, no matches

{
  "status": "success",
  "message": "Customer onboarding completed",
  "data": {
    "onboarding_id": 1024,
    "identity": {
      "verified": true,
      "identifier_type": "BVN",
      "first_name": "Amaka",
      "middle_name": "Chisom",
      "last_name": "Okafor",
      "date_of_birth": "1992-04-17",
      "gender": "Female",
      "phone": "08031234567"
    },
    "screening": {
      "sanctions": [],
      "peps": [],
      "adverse_media": [],
      "risk_level": "low"
    },
    "decision": "pass"
  }
}

Review — identity verified, PEP match found

{
  "status": "success",
  "message": "Customer onboarding completed",
  "data": {
    "onboarding_id": 1025,
    "identity": {
      "verified": true,
      "identifier_type": "NIN",
      "first_name": "Emeka",
      "last_name": "Nwosu",
      "date_of_birth": "1985-11-02",
      "gender": "Male"
    },
    "screening": {
      "sanctions": [],
      "peps": [
        {
          "name": "Emeka Nwosu",
          "pep_types": ["role.pep", "pep-class-2"],
          "gender": "male",
          "source": "OpenSanctions",
          "country": "Nigeria",
          "political_post": ["Former State Commissioner"]
        }
      ],
      "adverse_media": [],
      "risk_level": "medium"
    },
    "decision": "review"
  }
}

Fail — identity verification unsuccessful

{
  "status": "success",
  "message": "Customer onboarding completed",
  "data": {
    "onboarding_id": 1026,
    "identity": {
      "verified": false,
      "identifier_type": "BVN",
      "error": "Bank Verification Number (BVN) check failed: Invalid BVN provided"
    },
    "screening": {
      "sanctions": [],
      "peps": [],
      "adverse_media": [],
      "risk_level": "low",
      "note": "AML screening skipped: identity verification did not return a name"
    },
    "decision": "fail"
  }
}

Error Responses

HTTP Status	Message	Cause
`401`	`"Authorization token is missing"`	No `x-access-token` header
`401`	`"Authorization failed"`	Token not recognised or expired
`403`	`"Identity Verification suite isn't enabled for this branch"`	Feature not activated — contact support
`403`	`"Your account hasn't been verified for Identity Verification Suite"`	Admin account pending verification
`400`	`"country is required"`	Missing `country` field
`400`	`"identifier is required"`	Missing `identifier` field
`400`	`"Unsupported country '…'. Supported: …"`	Invalid `country` value
`400`	`"Unsupported identifier_type '…' for …. Supported: …"`	Invalid `identifier_type` for the given country

Authorizations

x-access-token

string

header

required

Your Adhere API secret key

Body

application/json

country

enum<string>

required

Country of the customer

Available options:

nigeria,

kenya,

ghana,

uganda,

rwanda

Example:

"nigeria"

identifier

string

required

The ID number to verify (BVN, NIN, National ID, etc.)

Example:

"12345678901"

identifier_type

string

Overrides the country default. Nigeria: bvn, nin, vnin. Others: national_id or ghana_id.

Example:

"bvn"

Response

Onboarding completed — check decision field for pass/review/fail

​Endpoint

​Request

​Headers

​Body Parameters

​Example

​Response

​Pass — identity verified, no matches

​Review — identity verified, PEP match found

​Fail — identity verification unsuccessful

​Error Responses

Authorizations

Body

Response

Endpoint

Request

Headers

Body Parameters

Example

Response

Pass — identity verified, no matches

Review — identity verified, PEP match found

Fail — identity verification unsuccessful

Error Responses