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.
If you use our SDK, the HMAC step will be abstracted,
and you don't need to do anything related to it.
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 BodyAuthorization: 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
id
Unique identifier generated by the VerifyMyContent API.
customer
Customer information
id
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 |
|
401 |
|
401 |
|
422 |
|
500 |
|
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"
}
{ "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" }
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.
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 BodyAuthorization: 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
id
Unique identifier generated by the VerifyMyContent API.
customer
Customer information
id
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 |
|
401 |
|
401 |
|
422 |
|
500 |
|
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"
}
{ "id": "ABC-123-5678-ABC", "status": "pending", "customer": { "id": "YOUR-USER-ID", "email": "person@example.com" }, "webhook": "https://example.com/webhook" }
Get Identity Verification
Authorization Header
Generate HMAC with: Request URIAuthorization: hmac YOUR-API-KEY:GENERATED-HMAC
Response parameters
id
Unique identifier generated by the VerifyMyContent API.
customer
Customer information
id
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 |
|
401 |
|
401 |
|
422 |
|
500 |
|
GET /api/v1/identity-verification/{ID} HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI
{ "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": "" }
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 BodyAuthorization: hmac YOUR-API-KEY:GENERATED-HMAC
Request parameters
id
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 |
|
401 |
|
401 |
|
422 |
|
500 |
|
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": ""
}
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
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.
<?php
hash_hmac('sha256', $input, 'API_SECRET');
Get allowed URLs
Retrieve a list of allowed redirect URLs.
Authorization Header
Generate HMAC with: Request URIAuthorization: hmac YOUR-API-KEY:GENERATED-HMAC
Response parameters
body
The list of Allowed Redirect URLs.
Error responses
Code | Description |
---|---|
401 |
|
500 |
|
GET /v1/business/allowed-redirects HTTP/1.1
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI
{ "body": [ "https://your-website.com/redirect-1", "https://your-website.com/redirect-2" ] }
Add Allowed URLs
Add one or more allowed redirect URLs.
Authorization Header
Generate HMAC with: Request BodyAuthorization: hmac YOUR-API-KEY:GENERATED-HMAC
Request parameters
body required
An array containing the allowed redirect URLs.
Error responses
Code | Description |
---|---|
401 |
|
500 |
|
PATCH /v1/business/allowed-redirects HTTP/1.1
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY
[
"https://your-website.com/redirect-1"
]
Replace All Allowed URLs
Replace any existing allowed redirect URLs with the provided list.
Authorization Header
Generate HMAC with: Request BodyAuthorization: hmac YOUR-API-KEY:GENERATED-HMAC
Request parameters
body required
An array containing the allowed redirect URLs.
Error responses
Code | Description |
---|---|
401 |
|
500 |
|
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"
]
Delete Allowed URLs
Remove one or more allowed redirect URLs.
Authorization Header
Generate HMAC with: Request BodyAuthorization: hmac YOUR-API-KEY:GENERATED-HMAC
Request parameters
body required
An array containing the allowed redirect URLs.
Error responses
Code | Description |
---|---|
401 |
|
500 |
|
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"
]