Checks
Interact with the Real ID checks API to retrieve and create ID checks for customers.
Create an ID check
To create an ID check via the API, you need to pass at minimum an email address or phone number.
But the more details the better, so the system can properly personalize the email and SMS message to the customer according to your templates.
POST https://real-id.getverdict.com/api/v1/checks
Parameters
In the body of the request, define the customer and the order if possible.
We recommend providing as much details as possible for the best synchonization of ID verification to Shopify tags on the customer and order.
However, the only required fields are at least an customer.email or a customer.phone to at minimum be able to deliver the ID check to the customer.
If present, the order.shopify_admin_graphql_id and customer.shopify_admin_graphql_id will be used the sync the ID check changes to the corresponding order and customer.
For example, when the customer completes the ID check their order will be tagged with ID verification completed.
For WooCommerce, the same behavior applies when the order.wc_id or customer.wc_id parameters are given.
- Shopify
- WooCommerce
{
"customer": {
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone": "+1224225555",
"shopify_admin_graphql_id": "gid://shopify/Customer/1234"
},
"order": {
"shopify_admin_graphql_id": "gid://shopify/Order/1234",
"name": "#1234"
}
}
{
"customer": {
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone": "+1224225555",
"wc_id": 1234
},
"order": {
"wc_id": 5678
}
}
Please note that any settings you provide in the ID check will override your settings defined in the Real ID app. So if you only provide the customer and order details for example, then your custom content, branding, rules like selfie capture, automatic reminders etc. defined in the app will be applied to these API created checks.
Customizing Check Theme & Content
By default, the ID check will use the content defined in the Settings area of the Real ID app. But you can control the content per ID check using the API instead.
You can pass a custom message to the check.intro_content parameter, as well as customize the theme using the check.theme parameter:
{
"customer": {
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone": "+1224225555",
"shopify_admin_graphql_id": "gid://shopify/Customer/1234"
},
"order": {
"shopify_admin_graphql_id": "gid://shopify/Order/1234",
"name": "#1234"
},
"check": {
"intro_content": "Hi [firstName], \n Your order [orderId] requires ID verification because it has been flagged as high risk by Shopify. \n Your order will process as soon as you complete ID verification, this is just an extra security measure to prevent misuse of your credit card."
"theme": {
"primary_color": "#FFFFFF",
"button_color: "#000000",
"logo_url": "https://example.com/logo.png"
}
}
}
The check.intro_content parameter supports short codes to reference data from the order and customer details.
The check.theme.primary_color and check.theme.button_color support color HEX codes.
Please provide a publicly available URL for the check.theme.logo_url, this URL will be used for both the email to customers as well as in the online ID verification flow.
Customizing ID check requirements
You can control if the ID check should require just an ID photo or both the ID photo and a matching headshot for additional verification with the check.images_required parameter.
{
"customer": {
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone": "+1224225555",
"shopify_admin_graphql_id": "gid://shopify/Customer/1234"
},
"order": {
"shopify_admin_graphql_id": "gid://shopify/Order/1234",
"name": "#1234"
},
"check": {
"images_required": "id"
}
}
The check.images_required accepts two different options:
"id"- only the ID photo is required for verification"idv"- both the ID photo and a matching headshot are required for verification
Skip emails and SMS messages
By default, the API will automatically send an email and text message to the customer with the ID check link. However, this may be an issue for testing, since you may want to use testing email addresses, or perhaps you want to better control messaging to your customers.
You can disable the email and SMS message by passing the deliver_checks option to the options in the request:
{
"customer": {
"email": "[email protected]"
},
"options": {
"deliver_check": false
}
}
This will simply create and return the ID check, but not deliver the ID check to the customer.
Response
After creating the ID check, the API will respond with a format like this:
- Shopify
- WooCommerce
{
"message": "Delivered ID check",
"check": {
"order": {
"id": "gid://shopify/Order/1234",
"name": "#1234"
},
"customer": {
"first_name": "John",
"last_name": "Smith",
"id": "gid://shopify/Customer/1234",
"phone": "+1224225555",
"email": "[email protected]"
},
"rules": {
"testing": true,
"signature_required": false,
"id_check_type": "idv",
"include_back_of_id": false,
"selfie_liveness": "straight"
},
"result": {
"scores": {},
"document": {}
},
"id": "7TWFOC-auPI",
"step": "delivered",
"shop_name": "real-id-dev.myshopify.com",
"created_at": "2023-03-14T03:22:00.219Z",
"platform": "shopify"
}
}
After creating the ID check, the API will respond with a format like this:
{
"message": "Delivered ID check",
"check": {
"order": {
"id": 5678
},
"customer": {
"first_name": "John",
"last_name": "Smith",
"id": 1234,
"phone": "+1224225555",
"email": "[email protected]"
},
"rules": {
"testing": true,
"signature_required": false,
"id_check_type": "idv",
"include_back_of_id": false,
"selfie_liveness": "straight"
},
"result": {
"scores": {},
"document": {}
},
"id": "7TWFOC-auPI",
"step": "delivered",
"shop_name": "real-id-dev.myshopify.com",
"created_at": "2023-03-14T03:22:00.219Z",
"platform": "wc"
}
}
There are fields automatically added to the ID check based on your settings within the app.
To change the liveness rules, or minimum age rules, open the Rules area in the Settings of the dashboard.
Retrieve an ID check
To retrieve an ID check, provide the unique ID of the check as a route parameter.
GET https://real-id.getverdict.com/api/v1/checks/{{checkId}}
Parameters
Include additional data using query parameters. By default this endpoint returns all text based data. To access the photos submitted for the ID check, pass the withPhotos query parameter:
GET https://real-id.getverdict.com/api/v1/checks/{{checkId}}?withPhotos=true
All photos will be provided as short lived URLs in the API response under the photos key.
Example Response
{
"check": {
"order": {
"id": null,
"name": null
},
"customer": {
"id": null,
"phone": null,
"email": "[email protected]"
},
"rules": {
"testing": true,
"signature_required": false,
"id_check_type": "idv",
"include_back_of_id": false
},
"result": {
"errors": [],
"signals": [],
"scores": {
"id": 0.9965,
"selfie": 0.9891,
"face_match": 0.8198
},
"document": {
"first_name": "TESTFIRSTNAME",
"last_name": "TESTFIRSTNAME",
"middle_name": null,
"verified_address": {
"unit": null,
"streetNumber": 1234,
"street": "Test St",
"country": "US",
"state": "OH",
"city": "Cleveland",
"postalCode": "44107"
},
"document_number": "15-239-1250",
"expiration_date": "04/24/2018",
"issue_date": "08/27/2015",
"birth_date": "06/14/1946",
"issuing_state": "CO",
"issuing_country": "US",
"type": "drivers-license"
}
},
"id": "abcedef123",
"step": "completed",
"shop_name": "real-id-dev.myshopify.com",
"created_at": "2022-12-09T15:20:35.136Z",
"platform": "shopify"
}
}
Using the response
With this response, you can craft the customer's ID check link for use within your own app to link the customer to their ID check.
The response's check.id field is the unique token for this ID check. You can append it to our hosting link to start the customer's ID check session:
https://idv.link/{{checkId}}
In our example response above, the unique check ID is abcedef123, so the link for this ID check sesison would be: https://idv.link/abcedef123.
Real ID securely stores customer PII data on your behalf. While you can access this data over the REST API securely, we highly recommend not downloading photos or customer data.
You will be responsible for maintaining secure access to this data, as well as fulfilling all legal retrieval and data deletion requests on the downloaded copies.
Delete ID check data
Real ID gives you the control to delete a customer's ID check data completely.
DELETE https://real-id.getverdict.com/api/v1/checks/{{checkId}}
This is an irreversible action.
The ID check records and corresponding images will be deleted immediately.
Parameters
No parameters are required.
Example Response
{
"message": "Check deleted.",
"check": {
"id": "abcedef"
}
}
Not all customer data can be deleted synchronously. All traces of customer data will be deleted within 30 days.