Attributes with Constraints
Attribute Description
Evident’s platform allows you to collect new information from the user and generate a new output attribute via a feature of the API called Constraints. The constraints are always in the form of a timestamp. The constraints inform the Evident platform that the output attribute (and thus its associated inputs) must be newer than the specified timestamp. If a value for the output attribute exists in the Evident platform that is newer than the timestamp, it will be returned. If not, the output attribute will require new inputs before being recalculated and returned.
We can use constraints in the scenario where we want to collect a new identity document in order to complete a second identity document verification and generate a new value for the output attribute. This is most often used when the prior verification Timed Out due to inadequate information being provided to Evident. When you create the new request with constraints, the Evident system will know to ignore the previously uploaded submission. The request with constraints will complete using the most recent uploaded image and a new value for the output attribute will be calculated. Your team can pull the most recently updated output attribute in order to get new results for a specific verification for the same user.
For the sake of simplicity, usually the constraint is set to about five minutes prior to the date that the request was created. This absorbs any small nuance in date calculations across different systems and time zones. Constraints can be used on an individual attribute within the request body, or for all the attributes. They can be applied to individual requests, or they can be applied to all requests. In order to determine which option works best for your business, think through the use flow options for your use case and follow any advice from the Evident Customer Success team that is specific to your use case.
Best Practices With Constraints
In general, to know you are applying constraints correctly in alignment with Evident best practices, you can abide by the following rule. If any service on the request is part of the identity assurance suite of products, then use constraints (-5s). The identity assurance suite of products are the following:
- Public Records Check
- Domestic Document Verification
- International Document Verification
- Selfie
- Liveness Check (Live Selfie)
If the request is any other kind of request, we usually recommend that you use constraints (-15m780K seconds) which allows any information from the past 6m to populate, but will ignore any information older than 6m, which ensures you get a fresh result.
How To Add Constraints to Your Requests
Constraints are only relevant for VerifyAPI. To be more specific, Constraints are implemented as an API parameter on an item in the attributesRequested array of a VerifyAPI request body. If constraints are specified, but new inputs are not received, the attribute will remain in pending state as the request does not recognize that there is any submission to complete the verification. Using Constraints will only require modifications in the VerifyAPI calls; all submission code should remain the same and be unaltered. However, keep in mind that the SubmitAPI or AssureSDK call to submit data must contain the "userIdentityToken" returned by the new request and NOT the “userIdentityToken” generated by the original request.
Relevant terms for this topic:
| Input | Description |
|
constraints |
A json object used with the attribute request in Verify API to indicate new outputs and inputs are requested |
| attribute_data | A json object that specifies the parameters for retrieving a newer version of the attributes |
| timestamp | UTC time stamp in seconds from which you would like to request a newer version of the attribute |
| $objectType | The type definition indicating this is an Evident Object, this should always be set to utctime. |
An example of the json object to specify a constraint is shown below:
"constraints": {
"attribute_data": {
"issued_after": {
"timestamp": 1533255487,
"$objectType": "utctime"
}
}
}
Example
An example curl command for creating an Identity verification request with constraints is below:
curl "https://verify.api.evidentid.com/api/v1/verify/requests" \
-X POST \
--header "Content-Type: application/json" \
-u ""<Third Party Name>:<API Key>" \
-d @request.json
Example request body request.json for creating a new attribute request:
{
"email": "example@email.com",
"description": "Enter Description Here",
"summary": "Enter Summary Here",
"attributesRequested": [
{
"attributeType": "identity_assurance.document_verification.verification_status",
"constraints": {
"attribute_data": {
"issued_after": {
"timestamp": 1533255487,
"$objectType": "utctime"
}
}
}
},
{
"attributeType": "core.fullname",
"constraints": {
attribute_data": {
"issued_after": {
"timestamp": 1533255487,
"$objectType": "utctime"
}
}
}
},
{
"attributeType": "core.address.fulladdress",
"constraints": {
"attribute_data": {
"issued_after": {
"timestamp": 1533255487,
"$objectType": "utctime"
}
}
}
},
{
"attributeType": "core.dateofbirth",
"constraints": {
"attribute_data": {
"issued_after": {
"timestamp": 1533255487,
"$objectType": "utctime"
}
}
}
},
{
"attributeType": "core.sex",
"constraints": {
"attribute_data": {
"issued_after": {
"timestamp": 1533255487,
"$objectType": "utctime"
}
}
}
}
]
}
Example response body after successful creation of attribute request:
{
"id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
"idownerId": "16a4d43f8a6ee2b0b2f47cfc1de728...",
"userIdentityToken": "eyJhbGciOiJSUzI1NiJ9.eyJub25jZSI6Ik..."
}
Example for entering input data:
curl "https://submit.api.evidentid.com/api/v1/requests" \
-X POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <token>" \
-d @request.json
Example request body request.json for submitting inputs for a identity verification using a US country document of drivers license id_type
{
"inputs": [
{
"type":"identity_assurance.document_verification.document_type",
"value":
{
"id_type":"drivers_license",
"country":"US"
}
},
{
"type":"identity_assurance.document_verification.drivers_license.image.front",
"value":
{
"$objectType":"BinaryData",
"data":"{{base64_encoded_binary_data}}",
"mime_type":"image/jpeg",
"metadata":
{
"cropped":false
}
}
},
{
"type":"identity_assurance.document_verification.drivers_license.image.back",
"value":
{
"$objectType":"BinaryData",
"data":"{{base64_encoded_binary_data}}",
"mime_type":"image/jpeg",
"metadata":
{
"cropped":false
}
}
}
]
}
Example response body after successful creation of attribute request where all attributes are submitted:
{
"success": true,
}
An example call to get requests
curl "https://verify.api.evidentid.com/api/v1/verify/requests?
email=example@email.com&userAuthenticationType=blindtrust" \
-X GET \
-u "<Third Party Name>:<API Key>"
Example response body to the above call to get rp requests. A 404 indicates that no requests could not be found for the idownerId.
[
{
"idOwnerId":"593970f0c7c57f2f2f@internal.blindtrust.thirdparty.idowner.evidentid.com",
"summary":"Enter Summary Here",
"description":"Enter Description Here",
"attributes":[
{
"values":["Valid", "Invalid"],
"type": "identity_assurance.document_verification.verification_status",
"status": "shared"
},
{
"values": [
{
"middle":"",
"$objectType":"Name",
"last":"Monell",
"prefix": null,
"suffix":null,
"first": "Sara"
},
{
"middle": "",
"last": "Monell",
"prefix": null,
"suffix": null,
"$objectType": "Name",
"first":"Sara"
}
],
"type": "core.fullname",
"status": "shared"
},
{
"values": [
{
"country": "US",
"city": "Atlanta",
"county": "FULTON",
"street_number": 75,
"neighborhood": "Midtown",
"state": "GA",
"postal_code": 30308,
"street_unit": null,
"$objectType": "Address",
"postal_code_suffix": null,
"street_name": "5th St NW"
},
{
"country": "US",
"city": "Atlanta",
"county": "FULTON",
"street_number": 75,
"neighborhood": "Midtown",
"state": "GA",
"postal_code": 30308,
"street_unit": null,
"$objectType": "Address",
"postal_code_suffix": null,
"street_name": "5th St NW"
}
],
"type": "core.address.fulladdress",
"status": "shared"
},
{
"values": [
{
"month": 10,
"year": 2000,
"$objectType": "date",
"day": 10
}
],
"type": "core.dateofbirth",
"status": "shared"
},
{
"values": [
"Female",
"Female"
],
"type": "core.sex",
"status": "shared"
}
],
"id": "15b0d077-a347-4830-8282-103b9bc8b5c5",
"issuedAt": {
"$objectType": "utctime",
"timestamp": 1533261211
}
}
]
When constraints are specified, all required inputs must also be supplied. New inputs must be submitted with the token "userIdentityToken" returned by the creation of the request with constraints.
Output attributes that have been reverified will return an array with all verification results that were calculated after the timestamp specified in the constraints of the request. The value in the first * index (0) is the most recent.