Skip to main content

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.

tip

If present, the order.shopify_admin_graphql_id will be used the sync the ID check changes to the corresponding order.

For example, when the customer completes the ID check their order will be tagged with ID verification completed.

The same behavior works for the customer.shopify_admin_graphql_id.

{
  "customer": {
    "firstName": "John",
    "lastName": "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"
  }
}

Response​

After creating the ID check, the API will respond with a format like this:

{
    "message": "Delivered ID check",
    "check": {
        "order": {
            "id": "gid://shopify/Order/1234",
            "name": "#1234"
        },
        "customer": {
            "first_name": "",
            "last_name": "",
            "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"
    }
}
note

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

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}}
danger

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",
  }
}

info

Not all customer data can be deleted synchronously. All traces of customer data will be deleted within 30 days.