Finding the right verification solution means gaining the flexibility to address any challenges by efficiently gaining the answers needed to do business. Evident’s powerful platform allows businesses to confidently, easily integrate with plenty of room to scale and add capabilities with minimal effort.
The system always works in the same, simple way:
How these steps play out depends on your chosen integration approach.
At Evident, we know firsthand that simplicity, security and scalability are both necessary and difficult to find. With 2 request creation methods, and 4 inputs submission integration options, Evident offers the flexibility you need to scale your Identity Proofing needs, and the simplicity to get up and running quickly.
Evident offers two methods to create a request. The easiest and quickest solution is by using the Evident Web Portal to manually create requests for individuals, or by uploading a list of individuals emails. VerifyAPI gives customers the ability to programmatically make requests, giving a higher level of flexibility and customization.
In this integration method you create requests manually through the customer portal
Verify gives you the ability to programmatically make requests to fit within your own flow, or to create a batch of requests all at once. Functionally for VerifyAPI is the same as creating a request through Evident’s Customer Portal, but allows you to incorporate our platform in your own native mobile or web application.
VerifyAPI is a RESTful JSON API that allows you to create a request for verification, and retrieve information about an existing request.
You will need your username and an API key to authenticate yourself with VerifyAPI using HTTP Basic Auth. If you did not receive your credentials as you signed up, please send an email to support@evidentid.com. You should have one API key for production use, and another API key for sandbox use. We will show you how to use an API key with the corresponding VerifyAPI instance.
https://verify.api.evidentid.com/api/v1https://verify.api.demo.evidentid.com/api/v1When presenting example calls like the one shown here, we will refer to your selected API as $VERIFY and your account name as $ACCOUNT.
Your API keys are secrets! You should call VerifyAPI endpoints from your server, and only your server. Be mindful of any leaks in how your key is used to ensure maximum protection.
For this integration, we create a request to verify information belonging to the end-user with the email jon.doe@somedomain.com. A verification request consists of attributes, which are small, verifiable data items used to build your own report of what you expect to be verified. The end-user will need to authenticate and submit personal data to the system for verification. Once the request is created, the end-user has 28 days from the time of their last submission to finish before the overall request times out.
| Field | Description |
|---|---|
email |
The email belonging to the user that owns the personal data you wish to verify. Depending on the integration mode, the user may be sent an email instructing them to answer a verification request. |
userId |
This is your own custom identifier that you may use to look up this end-user in the event you do not wish to use our identifiers. This allows better interoperability with your own database records. |
description |
A string that describes the intent of the verification request. This is used for your own records or communications with the end-user where applicable. |
userAuthenticationType |
This field controls how the end-user should authenticate with the system. For this integration mode, set this to blindtrust. |
attributesRequested |
An array of objects with key attributeType designating the data items you wish to verify. |
$ curl "$VERIFY/verify/requests" \
-X POST \
--header "Content-Type: application/json" \
-u "$ACCOUNT" \
-d @- << EOF
{
"email": "jon.doe@somedomain.com",
"userId": "jon.doe.12345",
"description": "Please provide your ServSafe certificate number",
"userAuthenticationType": "blindtrust",
"attributesRequested": [
{"attributeType": "certifications.servsafe.servsafe_food_handler.valid"}
]
}
EOF
Enter host password for user '$ACCOUNT': # Paste API key here to keep it out of history.
Here is the response from VerifyAPI indicating that a request was created. We’ll keep the id of the new request for reference later. The userIdentityToken can be a multi-use token to authenticate SubmitAPI calls, or single-use token which can traded by for a session token to authenticate a client using the SDK. Depending on you integration type, you may not need to use this token.
You can also keep the idOwnerId to reference the end user should you wish to see what verification requests apply to that user.
At this point, your system will wait for results using webhooks or additional VerifyAPI calls, discussed below.
{
"id":"3fc5ed0e-bb51-4c34-b294-0648969b7544",
"idOwnerId":"ae954a66-8c00-4bc2-90f7-93c21542dab5",
"userIdentityToken":"[lots of characters!]"
}Also known as “attribute overrides,” a constraint is a metadata object associated with one or more attributes in the payload of the VerifyAPI POST request which allows you to renew the value of an attribute. The Evident platform is designed to use any existing values for inputs and outputs on requests to reduce the amount of personally identifiable information passed over the internet.
Currently, the only constraint which can be attached to an attribute is a issued_after timestamp which indicates the earliest time at which any data used to calculate the results for an attribute can have been issued.
The issuedAt field is a UTC timestamp indicating some datetime. It is best to use a time in the recent past, i.e. 30s to prevent any submission issues caused by out of sync devices
{
//..
"attributesRequested": [
{
"attributeType": "certifications.servsafe.servsafe_food_handler.valid",
"constraints": {
"attribute_data": {
"issued_after": {
"$objectType": "utctime",
"timestamp": 1536160501
}
}
}
}
]
}
Evident offers 4 different methods for submitting users’ inputs. The easiest and quickest solution is to use Evident’s inputs submission UIs. We also offer an Input Submission API, SubmitAPI, which allows you to integrate Evident into your own application flow. Using SubmitAPI, we also offer a Javascript library for submitting inputs, as well as Android and iOS SDKs.
In this integration method, the user submits their inputs directly to Evident through Evident’s Submit UI
In this integration the user submits their information through the customer application using a RESTful JSON API.
Like VerifyAPI, SubmitAPI is a RESTful JSON service. You use SubmitAPI to send personal data up to the Evident platform. SubmitAPI powers the interactions for any experience in which someone represents an owner of personal data. In this integration mode, your server-side application is representing that owner.
https://submit.api.evidentid.com/api/v1/https://submit.api.demo.evidentid.com/api/v1/We will designate your chosen instance in code with $SUBMIT. Since a client of SubmitAPI is representing an owner of personal data, that client will need to authenticate using the userIdentityToken provided by VerifyAPI as a bearer token ($TOKEN in the code).
VerifyAPI and SubmitAPI may appear symmetrical, but they differ on how to interpret data. VerifyAPI can be used to verify if someone passed a background check, but that would make SubmitAPI call for a social security number, date of birth and consent information for regulatory reasons. You will need to know what inputs are needed to verify associated attributes in VerifyAPI. The call shown here submits data used to verify the certifications.servsafe.servsafe_food_handler.valid attributes.
curl $SUBMIT/requests" \
-X POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $TOKEN" \
-d @- << EOF
{
"inputs": [
{
"type": "core.firstname",
"value": "John"
},
{
"type": "core.lastname",
"value": "Smith"
},
{
"type": "certifications.servsafe.servsafe_food_handler.certnumber",
"value": "1234567"
}
]
}
EOFIn this integration method, the user’s data is submitted through your web application using a Javascript library
Now that we have a request for Evident to verify an end user’s personal information, That recipient will need to fill out a form to submit data to Evident and answer your request using their issued userIdentityToken. In this integration, you have full control over the UX for data collection. You only need to set up AssureSDK to submit the data to the platform, bypassing your servers.
To set up AssureSDK, download it here or load it from our CDN in an HTML page using this <script> tag.
<script type="text/javascript" src="https://cdn.evidentid.com/sdk/v1.0.4/assure-sdk.js"></script>
Once AssureSDK loads in your page, you can find its signature in the EvidentID.AssureSDK global variable. You will need to call its setUp function using the userIdentityToken from VerifyAPI. Place the value of the token where you see $TOKEN in this snippet. The function returns a Promise for undefined, but resolves when the SDK is ready to submit data to the Evident platform.
You may also specify an environment to select the VerifyAPI instance that matches the one that issued the token. Pass EvidentID.AssureSDK.ENVIRONMENTS.DEMO for sandbox use or EvidentID.AssureSDK.ENVIRONMENTS.PROD for production.
EvidentID.AssureSDK.setUp({
environment: EvidentID.AssureSDK.ENVIRONMENTS.DEMO, // Or .PROD for production
singleUseToken: '$TOKEN'
}).then(() => {
// I can submit values now!
}).catch((e) => {
alert(e.reason || e.message);
});
The last function to consider is EvidentID.AssureSDK.submitAttributes() which sends personal information directly to the Evident platform.
To understand the submission in context, let’s look at an example form that uses AssureSDK. Here is a complete HTML example that assumes the userIdentityToken is placed where you see $TOKEN in the code.
To understand the end-user’s perspective, save this code to servsafe.html and replace $TOKEN with the userIdentityToken value associated with the request. Open the page in your browser and you will see a form. You may continue to paste new tokens directly in the code yourself for the sake of experimentation, but the integration example simply serves a page to your user with a new token in place.
The flow is as follows:
EvidentID.AssureSDK global variable.EvidentID.AssureSDK.setUp() to get a session.EvidentID.AssureSDK.submitAttributes()<!DOCTYPE html>
<html>
<head>
<script type="text/javascript"
src="https://cdn.evidentid.com/sdk/v1.0.4/assure-sdk.js"></script>
<title>Provide your ServSafe credentials</title>
</head>
<body>
<script type="text/javascript">
// Set up the SDK using the token provided by VerifyAPI.
// The token can only be used once!
EvidentID.AssureSDK.setUp({
environment: EvidentID.AssureSDK.ENVIRONMENTS.DEMO,
singleUseToken: '$TOKEN'
}).then(() => {
document.getElementById('fields').setAttribute('style', 'display: grid');
}).catch((e) => {
alert(e.reason || e.message);
});
function sendDataToEvident() {
const firstname = document.getElementById('firstname').value;
const lastname = document.getElementById('lastname').value;
const certnumber = document.getElementById('certnumber').value;
EvidentID.AssureSDK.submitAttributes({
'core.firstname': firstname,
'core.lastname': lastname,
'certifications.servsafe.servsafe_food_handler.certnumber': certnumber,
}).then(() => {
alert('Success! You can proceed to check on the status of the request.');
}).catch((e) => {
alert(e.reason || e.message);
});
}
</script>
<fieldset id="fields" style="display: none">
First Name: <input id="firstname"><br>
Last Name: <input id="lastname"><br>
ServSafe certificate number: <input id="certnumber"><br>
<button onclick="sendDataToEvident(event)">Submit!</button>
</fieldset>
</body>
</html>If for some reason the user needs another session, request a new single-use token using the relevant request ID. In this example we use the request ID from the VerifyAPI response from earlier. The example integration shows a way to use newly issued tokens to dynamically serve authenticated HTML forms.
$ curl "$VERIFY/verify/requests/3fc5ed0e-bb51-4c34-b294-0648969b7544/authToken" \
-X GET \
-u "$ACCOUNT"
Enter host password for user '$ACCOUNT': # Paste API key here to keep it out of history.In this integration method, the user submits their inputs through your application using an Android or iOS SDK
In order to use AssureSDK for either iOS or Android you must first install the SDK. You can find direction on how to do so at the following links.
Android: https://github.com/evidentidpublic/mobile-AssureSDK-Android/releases/latest
iOS: https://github.com/evidentidpublic/mobile-AssureSDK-iOS/releases/tag/1.1.4
You will first need to create a client object by instantiating the SubmitApiClient class. The exact syntax looks slightly different between iOS and Android.
// Android
// Determine which environment to use:
val evidentEnvironment: ApiEnvironment = if (BuildConfig.DEBUG) ApiEnvironment.demo else ApiEnvironment.production
// Create the client:
val submitApiClient = SubmitApiClient(environment = evidentEnvironment)
//iOS
// Determine which environment to use:
let environment: ApiEnvironment = Configuration.RELEASE ? .production : .demo
// Create the client:
let client = SubmitApiClient(environment: environment)
In order to submit data using the client you have just created, you will first need to create an attribute instance by calling the appropriate method on the InputAttribute. In this example, we are submitting a String input attribute.
On both Android and iOS, the type parameter takes the attribute name, for example "core.ssn" and the value should be passed the string value input by the user.
//Android
val attributeType = "core.ssn"
val attribute: InputAttribute = InputAttribute.StringAttribute(attributeIdRaw = attributeType,
value = "<user-ssn>")
//iOS
let attributeType = "core.ssn"
let attribute: InputAttribute = .string(type: attributeType,
value: "<user-ssn>")
Finally, you will need to call the submitRequest method on the client object created above.
An array of attributes should be passed as the attributes argument. This array should contain any necessary input information for the verification request. The userIdentityToken should be passed the identity token returned in the VerifyAPI POST request. Finally, the completion parameter is passed a callback function to handle the success and failure cases.
//Android
submitApiClient.submitRequest(attributes = listOf(attribute),
userIdentityToken = "<request-specific-token>",
completion = object : SubmitApi.SubmitAttributeResult {
override fun error(error: Exception) {
// Handle error status here.
}
override fun success() {
// Handle sucessful attribute submission here.
}
})
//iOS
client.submitRequest(attributes: [attribute],
userIdentityToken: "<request-specific-token>",
completion: { (submitAttributesResult) in
switch submitAttributesResult {
case .success: print("handle success")
case .error(let error): print("handle error")
}
})If for some reason the user needs another session, request a new single-use token using the relevant request ID. In this example we use the request ID from the VerifyAPI response from earlier. The example integration shows a way to use newly issued tokens to dynamically serve authenticated HTML forms.
$ curl "$VERIFY/verify/requests/3fc5ed0e-bb51-4c34-b294-0648969b7544/authToken" \
-X GET \
-u "$ACCOUNT"
Enter host password for user '$ACCOUNT': # Paste API key here to keep it out of history.Once a request is out, we will send the owning party an email and reminders to submit their personal data. At this point you can monitor progress for when the verification request is complete using our webhook events. See Webhooks for setup instructions for your account.
This webhook notifies you that a request has completed. The payload includes:
eventType: rpRequestComlpleted indicating that the corresponding request has completed.rpRequestId: SOME_UUID for the corresponding request{
"rpRequestId": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
"eventType": "rpRequestCompleted"
}This webhook notifies you that a user has begun submitting inputs to a request. The payload includes:
eventType: rpRequestSubmissionCompleted indicating that the user has begun submitting inputs to the corresponding request.rpRequestId: SOME_UUID for the corresponding request{
"rpRequestId": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
"eventType": "rpRequestSubmissionCompleted"
}This webhook notifies that an email was sent unsuccessfully./ The payload includes:
eventType: notificationFailure indicating that an error was encountered sending an emailemail: some@email.address for the intended recipientrecipientType: RECIPIENT_TYPE for the recipient, i.e. id_owner, relying_party, etc.status: The reason for notification failure{
"eventType": "notificationFailure",
"email": "test@email.address",
"recipientType": "id_owner",
"status": "rejected"
}The easiest way to check the results of a request is to open the request in the Evident Customer Portal. The portal in addition to displaying the values for attributes if they are available, also displays request status information. There are 4 statuses that might display in the portal.
1. Complete Indicates that the request has finished processing and that all attributes are in a terminal state
2. Pending Indicates that a user has not uploaded their inputs to a request yet
3. In Process Indicates that a user has submitted their inputs, but the request has not yet completed
4. Timeout Indicates that there has been no action on an incomplete request in an allotted amount of time
Let’s head back to the server. We will use the request id given to us by VerifyAPI from earlier to check on the report.
$ curl "$VERIFY/verify/requests/3fc5ed0e-bb51-4c34-b294-0648969b7544" \
-X GET \
-u "<account>"
Enter host password for user '<account>': # Paste API key here to keep it out of history.The response may indicate that the results are not ready yet, in which case you can simply repeat the request in a minute or two. Eventually, the response will look something like this.
Here you see the attribute originally requested paired with a result. According to this, the attribute is flagged as “shared” due to the data submission.
The first value in the array located at values shows that the most recent submission of this set was fact-checked and deemed legitimate. A later verification might show false at the beginning to capture if the certificate was once valid, but is later invalid. What this means is that you can stay up to date on verifications. So if you issue this same request to the same person and get different results, you can respond accordingly.
If during onboarding you have opted into webhook and email notifications, then you will also be notified of these results automatically.
{
"description": "Please provide your certificate number",
"id": "98de3323-9661-4431-82aa-f58130954b99",
"idOwnerId": "d1424ecf212239341c2075a6147342a176268b690309f8e60402e3b99d124065@your-name.blindtrust.thirdparty.idowner.evidentid.com",
"issuedAt": {
"$objectType": "utctime",
"timestamp": 1536160501
},
"summary": "Information about your servsafe certification results",
"attributes": [
{
"status": "shared",
"type": "certifications.servsafe.servsafe_food_handler.valid",
"values": [
true
]
}
]
}There are 4 values which an attribute’s status field can return:
pending indicates that an attribute has either not started processing, or has started, but is not yet done processingshared indicates that an attribute has finished processing and that value has been returnedunavailable indicates that no value can be returned based on the inputs suppliedtimeout indicates no data has been submitted for the attribute in an allotted amount of time. The timeout period can be customized{
// ...
"attributes": [
{
"status": "pending",
"type": "certifications.servsafe.servsafe_food_handler.valid"
},
{
"status": "shared",
"type": "certifications.servsafe.servsafe_food_handler.valid",
"values": [
true,
]
},
{
"status": "unavailable",
"type": "certifications.servsafe.servsafe_food_handler.valid"
},
{
"status": "timeout",
"type": "certifications.servsafe.servsafe_food_handler.valid",
"values": [
true,
]
}
]
}VerifyAPI may respond with a 4xx status code. In this case, the response will have a JSON body with a reason key containing a readable string explaining the error (e.g. { "reason": "Invalid parameters specified." }).
5xx status codes—which are far less frequent—are typically indicative of a temporary outage.
When making requests against VerifyAPI, inspect the body of the response for 4xx error codes, make relevant adjustments to your request and try again. If the error persists despite a previously successful integration or an apparent inconsistency in the documentation, please contact support.