Documentation
The LEM Verify API and webhook integration is organised around REST using standard HTTP response codes and verbs. The current version of our API generates unique URLs for verifications, such as Combination, Document and Liveness, along with a notification system in the form of Webhooks.
When a verification has been processed by the system, LEM Verify will send a POST request (Webhooks) to the selected webhook URL with the result, details and PDF report for further processing by your system.
Base URL: https://api.lemverify.ioYour system needs to verify a person's identity for your KYC/AML process. By making a simple API call to "Request a Combination" (a combination of document and liveness verification) you will obtain a unique URL that your end users navigate to in order to securely submit their documents for processing by the LEM Verify systems.
Once the verification results have been processed, our systems will notify your server via a Webhook with the results of the verification for further processing or data storage by your server.
You wish to collect the individuals identity documents from within your own system (or already have them stored). By making an API call to our Upload a Document endpoint you can upload the identity document and receive a document verification report without having to manually enter any of the individuals information.
Once the verification results have been processed, our systems will notify your server via a Webhook with the results of the verification for further processing or data storage by your server.
Always use HTTPS.
The web hook post request contains sensitive personal identifiable information, so be very careful where you send this information!If the account balance is in arrears the webhook will not be sent, so please ensure your account has sufficient credits at all times, as we will not be able to send a POST request after failing due to insufficient credits.
Ensure you send the x-lem-key header, which is case sensitive, with each request. This can be obtained from the Webhooks section of Connections screen in your dashboard.
The LEM Verify API returns errors in the form of:
}
"type": "bad_request",
"message": "clientRef needs to be set as a String in the body."
}LEM Verify uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with LEM Verify's servers (these are rare).
| Code | Type | Description |
|---|---|---|
| 400 | bad_request | Your request needs to conform with the format set as per the documentation. The message field will suggest why the error might have occurred. |
| 401 | unauthorized | Please ensure you have set the x-lem-key header and that it's the correct key. This is can be obtained in the Webhooks Connections section of your dashboard.This could also be from insufficient credits on account for the service or you are not authorised to use the service, such as AML, without being approved first. |
| 422 | validation_error | The formatting or type of field sent does not conform to the documentation. The message field will suggest which field(s) are incorrect. |
| 404 | verification_not_found | The requested verification ID does not exist, ensure it's the System ID returned from the POST Webhook or that from the verification detail section. |
| 500 | internal_server_error | The LEM Server has encountered an error. Please contact support@lemverify.com with the supplied error code. |
To request a Facematch Verification (combination of documents and liveness), the following end point will return the unique URL for your end user to navigate to in order to complete the verification process.
To request a Facematch, make a HTTPS POST request to https://api.lemverify.io/api/v1/{account_id}/combination, where {account_id} is your LEM Verify account ID found in the Account Setup section of the dashboard.
The required Headers are:
The body must contain the following parameters:
| Field | Type | Required | Notes |
|---|---|---|---|
| clientRef | String | Mandatory | A String containing your own unique client reference number |
| redactMe | Boolean | Optional. Default is false | If set to true the documents will be redacted as per your settings. |
| amlRequired | Boolean | Optional. Default is false | If set to true an AML report will be generated, if enabled, as per your settings. |
| requestSmartsearchReport | Boolean | Optional. Default value is true | If this override is set to to false the system will not request a SmartSearch report, even if SmartSearch is enabled as default. |
| sendEmail | String | Optional | If you wish to also send an email (standard LEM content through the LEM email server) to a recipient please include a validated email address. The API will not validate the email address you supply. |
| sendSms | String | Optional | If you wish to also send an SMS (standard LEM content through the LEM SMS server) to a recipient please include a validated SMS number (with the country code, for example +44788xxxxxxx). The API will not validate the SMS number you supply. |
If the request is successful (200 response) then the response body will look similar to the following:
{
"id": "8a20ab90-37a1-11e9-a79c-891da1f19982",
"friendlyId": "vVebr9keyfZ2sctoZkMfBG",
"url": "https://lemverify.io/combination_verification.html?acc=gc15f4xa-8ea5-4b7e-94c0-cd0303d80aed",
"balance": 52,
"deliveryMethods": [
"API",
]
}The deliveryMethods array returns the transmission methods used in this request and will always contain "API". If an email was also sent this array will contain "EMAIL". If an SMS was also sent this array will contain "SMS" .
The id is a UUID for the verification, the friendlyId is a short uuid (mostly used for internal referencing at LEM), the balance is remaining credit balance on the LEM Verify account and the url is the url containing the unique URL for the verification (where the documents and liveness secure verification takes place).
The request will stay in the pending state for 30 days, until either the verification is completed or has been deleted via the LEM Verify dashboard.
Once a verification is completed it will be retained in the LEM Verify system for 90 days, where it will then be permanently deleted.
LEM Verify provides webhooks to notify you of processed verifications in the form of a POST request which is sent to your server with the body containing the details in JSON format.
You can enable webhooks by going to the Connections section of your dashboard and click the "FREE Setup" button which will show different settings like in the screen shot below:
Once a valid callback URL (https) has been entered and it returns at 200 code, the webhook is setup and ready to use. You can send test events to ensure your webhook implementation is working as required.
Events that trigger a POST request to your server are as follows:
We strongly recommend that you implement the Webhook Authentication layer, as described in the last section of this documentation.
Webhook requests will come from one of the following IPs, so please make sure that you whitelist these IPs to receive webhook notifications:
LEM Verify provides webhooks to notify you of processed verifications in the form a POST request to your server with the body containing the details in JSON format. Please respond with status 200 and an empty body if you have received the POST request.
Please note you may receive multiple post requests for the same verification, as the result might be updated at a later date with updated information.
The user-agent is LEMVerify/1.0.0
| Field | Type | Values | Notes |
|---|---|---|---|
| id | String | UUID for each verification. | |
| type | String | "COMBINATION" for combination verifications
"DOCUMENT" for single document verifications "LIVENESS" for standalone liveness verifications "AML_ALERT" for PEP/Sanction/Adverse Media alerts | The type of verification this event notification is for. |
| friendlyId | String | This will be the same as the clientRef used in the verification request. If this field is not supplied then one will be provided. | |
| processedAt | Signed 32bit integer | The UTC time this verification was processed. It is based on the number of seconds since 00:00:00 1 January 1970. | |
| startedAt | Signed 32bit integer | The UTC time the verification was started by the end user. It is based on the number of seconds since 00:00:00 1 January 1970. | |
| deletionAt | Signed 32bit integer | The UTC time the verification will be permanently deleted from the system. It is based on the number of seconds since 00:00:00 1 January 1970. | |
| result | String | "PASSED""REFER""ERROR""ALERT" | "PASSED" and "REFER" is the LEM Verify recommendation for supplied documentation, liveness video and AML verifications."ALERT" when the entity has been added to a new PEP/Sanction/Adverse media watchlist."ERROR" if the state of the verification is in error, please contact support@lemverify.com |
| referMessage | String | Explanation of why the supplied information should be investigated further. This field is only sent if the result is REFER. | |
| balance | int | Remaining credits on balance. | |
| person | Person | See the Person Object section for more details | Person object containing the extracted and determined information about the individual performing the verification. See the Person Object section for more details. This field will not be present for LIVENESS requests or for AML_ALERT alerts. |
| documents | array of Document | See the Document Object section for more details. | Array of Document objects containing the extracted and determined information about each document submitted by the individual performing the verification. See the Document Object section for more details. This field will not be present for LIVENESS requests or for AML_ALERT alerts. |
| liveperson | LivePerson | See the LivePerson Object section for more details | LivePerson object containing estimated information about the individual performing the verification. See the LivePerson Object section for more details. This field will not be present for DOCUMENT requests or for AML_ALERT alerts |
| alerts | array of Alert | See the Alert Object section for more details | An array of Alert objects containing information about a PEP, Sanction of Adverse Media watchlist they have recently been added to. See the Alert Object section for more details. This field will only be present when a requested on-going screen for an entity joins a new watchlist. This field will only be present for AML_ALERT alerts |
An example POST body for a Combination that has passed:
content-type: application/json; charset=utf-8
user-agent: LEMVerify/1.0.0
x-lemverify-signature: ???????
{
"id": "87dcfc90-3732-11e9-bf24-b52fdb098ba2",
"type": "COMBINATION",
"friendlyId": "eYsq3N8nNUk6YXzquWURVV",
"processedAt": 1550898774,
"startedAt": 1550898774,
"deletionAt": 1550907684,
"result": "PASSED",
"balance": 999,
"person": {
"title": "MR",
"forename": "JOHN",
"surname": "DOE",
"gender": "MALE",
"dob": {
"day": 19,
"month": 11,
"year": 1982
},
"address": {
"buildingNumber": "10",
"address1": "Prime Minister First Lord Of The Treasury",
"address2": "10 Downing Street",
"postTown": "London",
"county": "London",
"country": "England",
"postCode": "SW1A 2AA"
}
},
"documents": [
{
"type": "DRIVING_LICENSE",
"documentNumber": "TEST90000123456",
"expiryDate": {
"day": 1,
"month": 11,
"year": 2019
},
"issuingCountry": "GB",
"result": "REFER"
},
{
"type": "PASSPORT",
"documentNumber": "990099001",
"expiryDate": {
"day": 1,
"month": 11,
"year": 2019
},
"issuingCountry": "GB",
"result": "PASSED"
}
],
}
This object represents the information extracted from the documents about the individual performing the verification.
| Field | Type | Values | Notes |
|---|---|---|---|
| title | String | Identified title of the end user. | |
| forename | String | Identified forename of the end user. | |
| surname | String | Identified surname of the end user. | |
| gender | String | "MALE" "FEMALE" "UNKNOWN" | Identified gender of the end user. |
| dob | DOB Object |
{
"day": 19,
"month": 11,
"year": 1982
}
| A JSON object to represent the date of birth. Each field is an int. |
| address | Address Object |
{
"buildingNumber": "10",
"address1": "Prime Minister First Lord Of The Treasury",
"address2": "10 Downing Street",
"postTown": "London",
"county": "London",
"country": "England",
"postCode": "SW1A 2AA"
}
| A JSON object to represent the address of the individual. The
fields sent depend on the address, so treat each as optional apart
from the postCode
that will always be present in the object. Please note that this address is the end user populated address, unless this functionality is disabled on the account. If disabled then the address will be the one extracted from the document. |
Example JSON for the Person Object:
{
"title": "MR",
"forename": "JOHN",
"surname": "DOE",
"gender": "MALE",
"dob": {
"day": 19,
"month": 11,
"year": 1982
},
"address": {
"buildingNumber": "10",
"address1": "Prime Minister First Lord Of The Treasury",
"address2": "10 Downing Street",
"postTown": "London",
"county": "London",
"country": "England",
"postCode": "SW1A 2AA"
}
}
This object represents the information extracted from a document that has been submitted and the authenticity. This object also returns a result for the recommendation of the document for further investigation if required.
| Field | Type | Values | Notes |
|---|---|---|---|
| type | String | "DRIVING_LICENSE" "PASSPORT" "IDENTITY_CARD" "UNKNOWN" | Identified document type. |
| documentNumber | String | The unique document number extracted from the document. | |
| expiryDate | DOB Object | | A JSON object to represent the expiry date of the document. Each field is an int |
| issuingCountry | String | The ISO alpha-2 code representing the country that issued the document. | |
| result | String | "PASSED" "REFER" "ERROR" | LEM Verify recommendation for supplied document. |
Example JSON for the Document Object:
{
"type": "DRIVING_LICENSE",
"documentNumber": "TEST90000123456",
"expiryDate": {
"day": 1,
"month": 11,
"year": 2019
},
"issuingCountry": "GB",
"result": "REFER"
}This object represents the estimated information regarding the individual performing the verification.
| Field | Type | Values | Notes |
|---|---|---|---|
| age | int | Estimated age of individual | |
| gender | String | "MALE" "FEMALE" "UNKNOWN" | Identified gender of the end user. |
Example JSON for the Person Object:
{
"age": "38",
"gender": "MALE"
}
To retrieve the originally submitted documents by the end-user you can call
the following endpoint that returns urls to directly download the document
associated with the verification. The download url is signed against the
requesting IP address (/32) that has a valid x-lem-key and the webhooks
enabled.
Please note: the url will expire 5 minutes after the
request and can only be downloaded from the same IP address (/32) that
requested the download url.
To request a the document download
url(s), make a HTTPS GET request to https://api.lemverify.io/integrations/v1/webhooks/{accountId}/document/{systemId}/url, where {accountId} is your LEM Verify account ID found in
the
Account Setup section
of the dashboard and where {systemId} is the id sent through in the "POST Request Webhook" request (or you can use the System
ID that is on the verification page detail section).
The required
Headers are:
{
"report": "signed url of the LEM Verify report",
"amlReport": "signed url of the LEM Verify AML report (if enabled and available)",
"documentFront": "signed url of document front image",
"documentBack": "signed url of document back image (only present for Driving License and Identity Documents types)",
"redactedReport": "signed url of the redacted LEM Verify report (if enabled and available)",
"smartsearchReport": "signed url of the SmartSearch report (if enabled and available)",
"supportingDocument": "signed url of the supporting document uploaded by the end-user (if enabled and available)"
}If the verification ID does not exist a 404 code will be returned.
All download url requests are logged in the "Audit Trail" section of a requested verification. The audit logs can be viewed at the bottom of a verification page from your LEM Verify dashboard.
Deprecation of the Request Document Verification and Request Liveness Verification endpoints, in favour of the Request a Facematch Verification.
Updated the Facematch endpoint to allow the option of also sending
out an Email and/or SMS.
Addition of the supportingDocument field in the download documents
service, that will be present if an end-user has supplied this document.
Public release of our Anti-Money Laundering (AML) APIs, please see "Anti-Money Laundering (AML)" section.
Release of our "On-going Screening" alert API for Politically Exposed Person
(PEP), Sanction and Adverse Media matching and alerts. "POST Request
Webhook" updated to include the alerts object with details of the
alert match in real-time.
Updated the "Upload a Document" endpoint so that the reverse (verso) of the document can also be uploaded, which depends on the document type. The reverse is required for Driving License and Identity Card document types, along with the issuing country of the document.
Updated "Request a Combination Verification" endpoint to include optional redactMe and amlRequired for enabling redaction and AML reports respectively.
Updated "Request a Combination Verification" endpoint to include optional SmartSearch report override.
Updated "Download Documents" endpoint to include additional reports.
Added the "Download Documents" endpoint, that allows you to retrieve the originally submitted documents by the end-user for a verification.
"POST Request Webhook" updated to include the redactedReport base64
encoded pdf if present and redaction is enabled.
"Upload a Document" endpoint moved to public from private beta, allowing verification of uploaded documents.
Connections field added to the Post Request Webhook, that represents data returned from 3rd party systems that are connected to your LEM Verify account.
Initial release of the public API and Webhooks.