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

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

Customizing Check 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:

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

The check.intro_content parameter supports short codes to reference data from the order and customer details.

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:

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