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" }
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 person with the ID they scanned. |
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. |
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 person with the ID they scanned. |
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": ""
}