Identity Verification

SDK

We provide a PHP SDK containing an example integration to make it easier and faster to get ready to verify your customers:

VerifyMyContent Identity-Verification PHP SDK

Postman Workspace

We've created a Postman workspace specifically for our API, which contains example API calls that you can use to test and familiarise yourself with our API.

The workspace includes example API calls for each of our API endpoints, along with detailed descriptions of the request parameters and headers being used.

You can generate most of the client code to call our APIs using the Postman client code generator. With this feature, developers can select a range of programming languages, and generate the corresponding code with a few clicks.

Please note that while both the example API calls and the generated code can be a helpful starting point, it's important to thoroughly test your own API calls before deploying them in production. If you encounter any issues while using the example API calls, or if you have any questions about our API, please don't hesitate to reach out to our support team.

API Domain

Our API is designed to be used in two environments: a sandbox environment and a production environment.

The sandbox environment is intended for testing and development purposes, while the production environment is used for live data and real-world use cases.

To ensure the security and integrity of our API, we use separate API keys for each environment. This means that you will need to obtain different API keys for the sandbox and production environments, and should not use the same key for both.

Domain	Environment
https://oauth.verifymycontent.com	production
https://oauth.sandbox.verifymycontent.com	sandbox

Generating the HMAC header

To improve the security of the communication between your implementation and the VerifyMyContent API, we require you to generate a unique hexadecimal encoded SHA256 HMAC hash for each request, based on the input parameters.

The process of generating it depends on the language of your implementation.

Example

SDK php node.js

If you use our SDK, the HMAC step will be abstracted,
and you don't need to do anything related to it.

Copied!

<?php

hash_hmac('sha256', $input, 'API_SECRET');

Copied!

import { HmacSHA256 } from 'crypto-js';

HmacSHA256(JSON.stringify(input), 'API_SECRET').toString()

Copied!

Integration steps

Create Identity Verification

To create an identity verification, you'll need to send us the url the user will be redirected to after they finish the verification, some data for them so we can trigger reminders and notifications during the process, and a webhook to notify you when the identity verification status changes.

Important: Please generate a universally unique identifier (UUID v4) for each customer on your site. You should then use this same customer ID every time you call one of our APIs on behalf of that customer. This UUID should never change. For example, if the customer's username on your site changes, their UUID shouldn't.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

customer required

Customer information

id required

Customer's unique ID

email required

Customer's email address

redirect_uri optional

The URL where we will redirect the customer after they finish the identity verification process

webhook required

The URL where we will post status updates on the moderation.

Response parameters

Unique identifier generated by the VerifyMyContent API.

customer

Customer information

Customer's unique ID

Customer's email address

redirect_uri

The URL you should redirect the user to start the verification process.

webhook

The URL where we will post status updates on the moderation.

Error responses

Code	Description
400	`{"message": "the request could not be understood by the server due to malformed syntax", "status_code": 400}` Copied!
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
401	`{"message": "invalid client", "status_code": 401}` Copied!
422	`{"message": "invalid parameters", "status_code": 422}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl php

POST /api/v1/identity-verification HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "customer": {
        "id": "YOUR-USER-ID",
        "email": "person@example.com"
    },
    "redirect_uri": "https://verifymy.io",
    "webhook": "https://example.com/webhook"
}

Copied!

curl -d '{"customer": {"id": "YOUR-USER-ID", "email": "person@example.com"}, "redirect_uri": "https://verifymy.io", "webhook": "https://example.com/webhook"}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
-X POST https://oauth.sandbox.verifymycontent.com/api/v1/identity-verification

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyContent\IdentityCheck\VMC;

$vmc = new VMC(getenv('VMC_API_KEY'), getenv('VMC_API_SECRET'));
//$vmc->useSandbox();

$response = $vmc->createIdentityVerification([
    "customer" => [
        "id" => "YOUR-CUSTOMER-UNIQUE-ID",
        "email" => "person@example.com",
        "phone" => "+4412345678"
    ],
    "redirect_uri" => "https://example.com/callback",
    "webhook" => "https://example.com/webhook",
]);

Copied!

Response 201: (application/json)

{
  "id": "ABC-123-5678-ABC",
  "customer": {
    "id": "YOUR-USER-ID",
    "email": "person@example.com"
  },
  "redirect_uri": "https://.../v/ABC-123-5678-ABC",
  "webhook": "https://example.com/webhook"
}

Copied!

Verify Selfie and Document

To verify selfies and documents, you'll need to upload the user's selfie and a photo of their document. Additionally, you'll need to provide some user data so we can trigger reminders and notifications during the process, as well as a webhook to notify you when the identity verification status changes.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

customer required

Customer information

id required

Customer's unique ID

email required

Customer's email address

selfie required

Selfie photo in base64 format

document required

Customer document information

type required

Important: The document must contain a photo of the holder for us to match with their selfie.

It can be one of these values. It defaults to passport.

Type	Description
IdCard	A government-issued ID card with personal details and a photo for identity verification
DriverLicense	A document permitting an individual to drive, also used as an ID
Passport	A travel document that certifies identity and nationality, used for international travel
ResidencePermit	A document allowing a non-citizen to reside in a country, often including biometric data

country required

Country of document

Use 'Code' column to populate 'country' parameter.

Code	Country
afg	Afghanistan
alb	Albania
dza	Algeria
and	Andorra
ago	Angola
aia	Anguilla
atg	Antigua and Barbuda
arg	Argentina
arm	Armenia
aus	Australia
aut	Austria
aze	Azerbaijan
bhs	Bahamas
bhr	Bahrain
bgd	Bangladesh
brb	Barbados
blr	Belarus
bel	Belgium
blz	Belize
ben	Benin
bmu	Bermuda
btn	Bhutan
bol	Bolivia (Plurinational State of)
bih	Bosnia and Herzegovina
bwa	Botswana
bra	Brazil
brn	Brunei Darussalam
bgr	Bulgaria
bfa	Burkina Faso
bdi	Burundi
cpv	Cabo Verde
khm	Cambodia
cmr	Cameroon
can	Canada
cym	Cayman Islands
caf	Central African Republic
tcd	Chad
chl	Chile
chn	China
col	Colombia
com	Comoros
cog	Congo
cod	Congo, Democratic Republic of the
cri	Costa Rica
hrv	Croatia
cub	Cuba
cyp	Cyprus
cze	Czechia
civ	Côte d'Ivoire
dnk	Denmark
dji	Djibouti
dma	Dominica
dom	Dominican Republic
ecu	Ecuador
egy	Egypt
slv	El Salvador
gnq	Equatorial Guinea
eri	Eritrea
est	Estonia
swz	Eswatini
eth	Ethiopia
fji	Fiji
fin	Finland
fra	France
pyf	French Polynesia
gab	Gabon
gmb	Gambia
geo	Georgia
deu	Germany
gha	Ghana
gib	Gibraltar
grc	Greece
grd	Grenada
gtm	Guatemala
gin	Guinea
gnb	Guinea-Bissau
guy	Guyana
hti	Haiti
vat	Holy See
hnd	Honduras
hkg	Hong Kong
hun	Hungary
isl	Iceland
ind	India
idn	Indonesia
irn	Iran (Islamic Republic of)
irq	Iraq
irl	Ireland
imn	Isle of Man
isr	Israel
ita	Italy
jam	Jamaica
jpn	Japan
jor	Jordan
kaz	Kazakhstan
ken	Kenya
kir	Kiribati
prk	Korea (Democratic People's Republic of)
kor	Korea, Republic of
rks	Kosovo
kwt	Kuwait
kgz	Kyrgyzstan
lao	Lao People's Democratic Republic
lva	Latvia
lbn	Lebanon
lso	Lesotho
lbr	Liberia
lby	Libya
lie	Liechtenstein
ltu	Lithuania
lux	Luxembourg
mdg	Madagascar
mwi	Malawi
mys	Malaysia
mdv	Maldives
mli	Mali
mlt	Malta
mrt	Mauritania
mus	Mauritius
mex	Mexico
mda	Moldova, Republic of
mco	Monaco
mng	Mongolia
mne	Montenegro
msr	Montserrat
mar	Morocco
moz	Mozambique
mmr	Myanmar
nam	Namibia
nru	Nauru
npl	Nepal
nld	Netherlands
nzl	New Zealand
nic	Nicaragua
ner	Niger
nga	Nigeria
mkd	North Macedonia
nor	Norway
omn	Oman
pak	Pakistan
plw	Palau
pse	Palestine, State of
pan	Panama
png	Papua New Guinea
pry	Paraguay
per	Peru
phl	Philippines
pol	Poland
prt	Portugal
qat	Qatar
rou	Romania
rus	Russian Federation
rwa	Rwanda
shn	Saint Helena, Ascension and Tristan da Cunha
kna	Saint Kitts and Nevis
lca	Saint Lucia
vct	Saint Vincent and the Grenadines
wsm	Samoa
smr	San Marino
stp	Sao Tome and Principe
sau	Saudi Arabia
sen	Senegal
srb	Serbia
syc	Seychelles
sle	Sierra Leone
sgp	Singapore
svk	Slovakia
svn	Slovenia
slb	Solomon Islands
som	Somalia
zaf	South Africa
ssd	South Sudan
esp	Spain
lka	Sri Lanka
sdn	Sudan
sur	Suriname
swe	Sweden
che	Switzerland
syr	Syrian Arab Republic
twn	Taiwan, Province of China
tjk	Tajikistan
tza	Tanzania, United Republic of
tha	Thailand
tls	Timor-Leste
tgo	Togo
ton	Tonga
tto	Trinidad and Tobago
tun	Tunisia
tur	Turkey
tkm	Turkmenistan
tca	Turks and Caicos Islands
tuv	Tuvalu
uga	Uganda
ukr	Ukraine
are	United Arab Emirates
gbr	United Kingdom of Great Britain and Northern Ireland
usa	United States of America
ury	Uruguay
uzb	Uzbekistan
vut	Vanuatu
ven	Venezuela (Bolivarian Republic of)
vnm	Viet Nam
vgb	Virgin Islands (British)
yem	Yemen
zmb	Zambia
zwe	Zimbabwe

front required

Front of document photo in base64 format

back required

Back of document photo in base64 format.

For the documents below, this field is required

Type
IdCard
DriverLicense
ResidencePermit

webhook required

The URL where we will post status updates on the moderation.

Response parameters

Unique identifier generated by the VerifyMyContent API.

customer

Customer information

Customer's unique ID

Customer's email address

webhook

The URL where we will post status updates on the moderation.

Error responses

Code	Description
400	`{"message": "the request could not be understood by the server due to malformed syntax", "status_code": 400}` Copied!
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
401	`{"message": "invalid client", "status_code": 401}` Copied!
422	`{"message": "invalid parameters", "status_code": 422}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl php

POST /api/v1/identity-verification/selfie-document-validation HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "customer":{
        "id":"YOUR-USER-ID",
        "email":"person@example.com",
        "selfie": "selfie-base64",
        "document": {
            "type":"Passport",
            "country": "gbr",
            "front": "document-front-base64",
            "back": "document-back-base64"
    },
    "webhook": "https://example.com/webhook"
}

Copied!

curl -d '{
    "customer":{
        "id":"YOUR-USER-ID",
        "email":"person@example.com",
        "selfie": "selfie-base64",
        "document": {
            "type":"Passport",
            "country": "gbr",
            "front": "document-front-base64",
            "back": "document-back-base64"
    },
    "webhook": "https://example.com/webhook"
}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
-X POST https://oauth.sandbox.verifymycontent.com/api/v1/identity-verification/selfie-document-validation

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyContent\IdentityCheck\VMC;

$vmc = new VMC(getenv('VMC_API_KEY'), getenv('VMC_API_SECRET'));
//$vmc->useSandbox();

$response = $vmc->createIdentityVerification([
    "customer" => [
        "id" => "YOUR-CUSTOMER-UNIQUE-ID",
        "email" => "person@example.com",
        "phone" => "+4412345678",
        "selfie" => "selfie-base64",
        "document" => [
            "type" => "Passport",
            "country" => "gbr",
            "front" => "document-front-base64",
            "back" => "document-back-base64"
        ]
    ],
    "webhook" => "https://example.com/webhook",
]);

Copied!

Response 201: (application/json)

{
  "id": "ABC-123-5678-ABC",
  "status": "pending",
  "customer": {
    "id": "YOUR-USER-ID",
    "email": "person@example.com"
  },
  "webhook": "https://example.com/webhook"
}

Copied!

Get Identity Verification

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Response parameters

Unique identifier generated by the VerifyMyContent API.

customer

Customer information

Customer's unique ID

Customer's email address

redirect_uri

The URL you should redirect the user to start the verification process.

webhook

The URL where we will post status updates on the moderation.

status

It represents the current status of the identity verification flow. It can be one of the following:

Status	Description
pending	The verification is pending and the user has not yet started the verification process.
started	The verification has started and the user has been redirected to the verification page.
expired	The verification has expired (5 days after creation) and the user has not completed the verification process.
failed	The verification has failed. The user attempted multiple times but didn't succeed.
approved	The verification has been approved. The user has successfully completed the verification process.

reason

It represents the reason for an identity verification failure. It can be one of the following:

Reason	Description
expired_id	ID Document expired.
id_scan_error	We couldn't extract the required information from the person’s ID
idv_error	We were unable to complete your request. Please try again.
invalid_id	ID Document not supported or invalid.
liveness_error	Liveness anti-spoofing check failed during selfie-video.
minor	This person is under 18.
partial_id	A part of the person's ID was covered, so we couldn't extract the required information.
photo_mismatch	We couldn't match the device operator with the expected person.
poor_id_scan_error	We couldn't extract the required information from the person’s ID due to poor photo quality.
potential_fraud	We detected a possible fraud attempt.
server_error_unavailable	The service is unavailable. Please try again.

Error responses

Code	Description
400	`{"message": "the request could not be understood by the server due to malformed syntax", "status_code": 400}` Copied!
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
401	`{"message": "invalid client", "status_code": 401}` Copied!
422	`{"message": "invalid parameters", "status_code": 422}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl php

GET /api/v1/identity-verification/{ID} HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl -H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI" \
https://oauth.sandbox.verifymycontent.com/api/v1/identity-verification/{ID}

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyContent\IdentityCheck\VMC;

$vmc = new VMC(getenv('VMC_API_KEY'), getenv('VMC_API_SECRET'));
//$vmc->useSandbox();

$response = $vmc->getIdentityVerification("ID");

Copied!

Response 200: (application/json)

{
  "id": "ABC-123-5678-ABC",
  "customer": {
    "id": "YOUR-USER-ID",
    "email": "person@example.com"
  },
  "redirect_uri": "https://.../v/ABC-123-5678-ABC",
  "webhook": "https://example.com/webhook",
  "status": "approved",
  "reason": ""
}

Copied!

Sample Webhook Notification

When the identity verification status changes, we will send a webhook notification to the url you provided when you created the identity verification.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

Unique identifier generated by the VerifyMyContent API.

customer_id

Customer identifier you provided while creating the identity verification.

status

It represents the current status of the identity verification flow. It can be one of the following:

Status	Description
pending	The verification is pending and the user has not yet started the verification process.
started	The verification has started and the user has been redirected to the verification page.
expired	The verification has expired (5 days after creation) and the user has not completed the verification process.
failed	The verification has failed. The user attempted multiple times but didn't succeed.
approved	The verification has been approved. The user has successfully completed the verification process.

reason

It represents the reason for an identity verification failure. It can be one of the following:

Reason	Description
expired_id	ID Document expired.
id_scan_error	We couldn't extract the required information from the person’s ID
idv_error	We were unable to complete your request. Please try again.
invalid_id	ID Document not supported or invalid.
liveness_error	Liveness anti-spoofing check failed during selfie-video.
minor	This person is under 18.
partial_id	A part of the person's ID was covered, so we couldn't extract the required information.
photo_mismatch	We couldn't match the device operator with the expected person.
poor_id_scan_error	We couldn't extract the required information from the person’s ID due to poor photo quality.
potential_fraud	We detected a possible fraud attempt.
server_error_unavailable	The service is unavailable. Please try again.

Error responses

Code	Description
400	`{"message": "the request could not be understood by the server due to malformed syntax", "status_code": 400}` Copied!
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
401	`{"message": "invalid client", "status_code": 401}` Copied!
422	`{"message": "invalid parameters", "status_code": 422}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

Webhook Call

http curl

POST /your-path HTTP/1.1
Host: https://your-domain.com
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "id": "ABC-123-5678-ABC",
    "customer_id": "YOUR-USER-ID",
    "status": "approved",
    "reason": ""
}

Copied!

curl -d '{"id": "ABC-123-5678-ABC", "customer_id": "YOUR-USER-ID", "status": "approved", "reason": ""}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
-X POST https://your-domain.com/your-path

Copied!

Response 2xx

Allowed Redirect URLs

These changes will come into effect from 14:00 BST on 19th July 2024. URLs that are allowed to be redirected to after a successful verification.

Generating the HMAC header

The process of generating it depends on the language of your implementation.

Example

php node.js

<?php

hash_hmac('sha256', $input, 'API_SECRET');

Copied!

import { HmacSHA256 } from 'crypto-js';

HmacSHA256(JSON.stringify(input), 'API_SECRET').toString()

Copied!

Get allowed URLs

Retrieve a list of allowed redirect URLs.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Response parameters

body

The list of Allowed Redirect URLs.

Error responses

Code	Description
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl

GET /v1/business/allowed-redirects HTTP/1.1
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl https://oauth.sandbox.verifymycontent.com/v1/business/allowed-redirects
    --header 'Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI'

Copied!

Response 200: (application/json)

{
  "body": [
    "https://your-website.com/redirect-1",
    "https://your-website.com/redirect-2"
  ]
}

Copied!

Add Allowed URLs

Add one or more allowed redirect URLs.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

body required

An array containing the allowed redirect URLs.

Error responses

Code	Description
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl

PATCH /v1/business/allowed-redirects HTTP/1.1
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY
[
    "https://your-website.com/redirect-1"
]

Copied!

curl -X PATCH https://oauth.sandbox.verifymycontent.com/v1/business/allowed-redirects
    --header 'Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY'
    --data '[
    "https://your-website.com/redirect-1"
]'

Copied!

Response 204

Replace All Allowed URLs

Replace any existing allowed redirect URLs with the provided list.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

body required

An array containing the allowed redirect URLs.

Error responses

Code	Description
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl

PUT /v1/business/allowed-redirects HTTP/1.1
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY
[
    "https://your-website.com/new-redirect-url"
]

Copied!

curl -X PUT https://oauth.sandbox.verifymycontent.com/v1/business/allowed-redirects
    --header 'hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY'
    --data '[
    "https://your-website.com/new-redirect-url"
]'

Copied!

Response 204

Delete Allowed URLs

Remove one or more allowed redirect URLs.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

body required

An array containing the allowed redirect URLs.

Error responses

Code	Description
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl

DELETE /v1/business/allowed-redirects HTTP/1.1
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY
[
    "https://your-website.com/redirect-1",
    "https://your-website.com/redirect-2"
]

Copied!

curl -X DELETE https://oauth.sandbox.verifymycontent.com/v1/business/allowed-redirects
    --header 'Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY'
    --data '[
    "https://your-website.com/redirect-1",
    "https://your-website.com/redirect-2"
]'

Copied!

Response 204

Identity Verification

SDK​

Postman Workspace

API Domain

Generating the HMAC header

Integration steps​

Create Identity Verification

Authorization Header

Request parameters

Response parameters

Error responses

Verify Selfie and Document

Authorization Header

Request parameters

Response parameters

Error responses

Get Identity Verification

Authorization Header

Response parameters

Error responses

Sample Webhook Notification

Authorization Header

Request parameters

Error responses

Allowed Redirect URLs​

Generating the HMAC header

Get allowed URLs​

Authorization Header

Response parameters

Error responses

Add Allowed URLs​

Authorization Header

Request parameters

Error responses

Replace All Allowed URLs​

Authorization Header

Request parameters

Error responses

Delete Allowed URLs​

Authorization Header

Request parameters

Error responses

SDK

Integration steps

Allowed Redirect URLs

Get allowed URLs

Add Allowed URLs

Replace All Allowed URLs

Delete Allowed URLs