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
}
}
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
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": "uNjDSvOnuQK",
"step": "completed",
"shop_name": "real-id-dev.myshopify.com",
"created_at": "2022-12-09T15:20:35.136Z",
"platform": "shopify"
}
}
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.