Getting Started with Evident

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:

1. You create a verification request using one or more attributes, such as if someone has a valid boating insurance or passes a background check.
2. The end-user that owns the personal data you wish to verify submits their data to the platform.
3. The system runs verifications to fulfill your request.
4. The system reports an up-to-date result of the verifications, enabling your business operations.

How these steps play out depends on your chosen integration approach.

Integration Options

At Evident, we know firsthand that simplicity, security and scalability are both necessary and difficult to find. With four integration options, developers and deployment teams can choose the path that best fits with their resources and requirements. From the Evident Portal which allows businesses to start verifications in minutes with limited integration to the VerifyAPI that enables end to end customization, our Identity Assurance Platform offers a flexible, intuitive and secure solution to address your verification needs.

Customer Portal and Evident Submit UIs

If you want to get started immediately with minimal effort, you can use Evident’s own integrations using your account. If this mode is your preference, please contact support to get started.

VerifyAPI and Evident Submit UIs

In this integration mode, your backend integrates with the Evident platform while we take care of collecting data from your customers in our brandable interface.

Create a request with VerifyAPI

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.

• The production VerifyAPI is located at https://verify.api.evidentid.com/api/v1
• The sandbox VerifyAPI is located at https://verify.api.demo.evidentid.com/api/v1

When 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.

$ 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 is a multi-use token that an end-user can use to authenticate against an Evident web app. You normally do not need to use this token yourself. We send an email to the end-user for you.

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!]"
}

Webhook notifications

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.

$ 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.

Check results with VerifyAPI

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.

{
    // ...
    "attributes": [
        {
            "status": "shared",
            "type": "certifications.servsafe.servsafe_food_handler.valid",
            "values": [
                true,
            ]
        }
    ]
}

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.

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

Error handling

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.

VerifyAPI and AssureSDK

This integration mode applies in the event you want a backend integration and a client-side web browser integration. Using this approach you avoid handling personal information on your servers but may still allow an end-user to enter their information using your own branded interface. This integration mode uses VerifyAPI, a RESTful JSON API used to manage requests for verification and AssureSDK, a JavaScript library used in a web browser to ensure that sensitive data never reaches your backend.

You will need to set up webhooks to capture notifications that verification results are ready to be retrieved with VerifyAPI, or you may also check the status yourself.

To see this integration mode in action, take a look at the source code for an example VerifyAPI+AssureSDK integration.

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

Create a request with VerifyAPI

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.

• The production VerifyAPI is located at https://verify.api.evidentid.com/api/v1
• The sandbox VerifyAPI is located at https://verify.api.demo.evidentid.com/api/v1

When 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.

$ 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": "embedded",
    "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 is a single-use token that an end-user will exchange for a session in a web app. You can also keep the idOwnerId to reference the end user should you wish to see what verification requests apply to that user.

We can use the request ID to both look up the status and results of the request at any time, or to issue a new userIdentityToken if needed.

Now we will need to serve an HTML page that uses the userIdentityToken to initialize AssureSDK, create a session for the end user, and submit data to verify.

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

AssureSDK setup

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);
});

Submitting data with AssureSDK

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:

1. Load AssureSDK from a CDN. The SDK appears the EvidentID.AssureSDK global variable.
2. Call EvidentID.AssureSDK.setUp() to get a session.
3. Submit form data to Evident using 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>

Re-issuing tokens

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.

Webhook notifications

You can monitor progress for this integration using our webhook events. See Webhooks for setup instructions for your account.

{
    // ...
    "attributes": [
        {
            "status": "shared",
            "type": "certifications.servsafe.servsafe_food_handler.valid",
            "values": [
                true,
            ]
        }
    ]
}

Check results with VerifyAPI

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.

{
    // ...
    "attributes": [
        {
            "status": "shared",
            "type": "certifications.servsafe.servsafe_food_handler.valid",
            "values": [
                true,
            ]
        }
    ]
}

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.

// Sync
try {
  AssureSDK.createDocumentPageFromDataUrl(...)
} catch (e) {
  if (e.reason) console.log(e.reason, e.extra); // base/bad-arguments undefined
}

// Async
AssureSDK.submitAttributes(...).catch((e) => {
  if (e.reason) console.log(e.reason, e.extra); // service/rate-limited 14
});

Error handling

When integrating, errors may occur on either VerifyAPI or AssureSDK. Here we cover each error space.

VerifyAPI errors

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 documentation, please contact support.

AssureSDK

AssureSDK will throw Error objects under a few rules:

• The Error object will have a reason and/or a extra property, unless if the error is of a built-in type like TypeError.
• If an extra property appears, it will hold information related to the error.
• If the function that encounters an error returns a promise, the error will only appear in the promise’s rejection handler. The error will not be thrown syncronously.

A reason code has the format <facility>/<cause>, where <facility> is the scope of the error and <cause>is the specific problem within that facility..

AssureSDK Error codes

// Sync
try {
  AssureSDK.createDocumentPageFromDataUrl(...)
} catch (e) {
  if (e.reason) console.log(e.reason, e.extra); // base/bad-arguments undefined
}

// Async
AssureSDK.submitAttributes(...).catch((e) => {
  if (e.reason) console.log(e.reason, e.extra); // service/rate-limited 14
});

VerifyAPI and SubmitAPI

This integration mode offers complete customization of the platform end-to-end. In this integration your server gains visibility into personal data. Use this approach when your integration and envisioned experience can support all related security and regulatory responsibilities.

Create a request with VerifyAPI

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.

• The production VerifyAPI is located at https://verify.api.evidentid.com/api/v1
• The sandbox VerifyAPI is located at https://verify.api.demo.evidentid.com/api/v1

When 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.

$ 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 is a multi-use token that you will need to authenticate against SubmitAPI. You can also keep the idOwnerId to reference the end user should you wish to see what verification requests apply to that user. We can use the request ID to both look up the status and results of the request at any time.

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

Submitting with SubmitAPI

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.

• The production SubmitAPI is located at https://submit.api.evidentid.com/api/v1/
• The sandbox SubmitAPI is located at 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"
        }
    ]
}
EOF

Webhook notifications

You can monitor progress for this integration using our webhook events. See Webhooks for setup instructions for your account.

{
    "eventType": "notificationFailure",
    "email": <the email address that could not be emailed>,
    "recipientType": <the type of user that could not be emailed>,
    "status": <the reason for delivery failure>
}

Check results with VerifyAPI

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.

{
    // ...
    "attributes": [
        {
            "status": "shared",
            "type": "certifications.servsafe.servsafe_food_handler.valid",
            "values": [
                true,
            ]
        }
    ]
}

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.

{
    "eventType": "notificationFailure",
    "email": <the email address that could not be emailed>,
    "recipientType": <the type of user that could not be emailed>,
    "status": <the reason for delivery failure>
}

Error handling

Both VerifyAPI and SubmitAPI 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, 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.

{
    "eventType": "rpRequestCompleted",
    "rpRequestId": <the ID of the RP request that was completed>
}

Webhook notifications

You can monitor Evident platform events using webhooks. You provide to the platform some URLs that the Evident platform sends POST requests to at key moments along with a JSON payload. Should one of these POST requests fails, it will attempt to POST to the webhook as many times as you specify, with as much time as you’d like between each retry.

To set up a webhook, you will need the following things:

• The event to monitor
• Webhook URL
• Retry wait time on unsuccessful POST
• Number of times to retry

Send this information to our support team and your account will be configured accordingly.

Below you will find all supported events.

rpRequestCompleted

{
    "eventType": "rpRequestCompleted",
    "rpRequestId": <the ID of the RP request that was completed>
}