Canadian DMV API v1

This section describes how to integrate with Canadian DMV v1 API. For developers already familiar with our platform, the v1 API adheres to the standardized request/response models used by services like DMV, IdentiFraud, etc.

Endpoint URLs

https://screening.idware.net/api/Check
or
https://screening.idscan.net/api/Check

HTTP Method

POST

Content Type

application/json

Authorization

This API uses Bearer Token authentication. Include the following header in your request:

Authorization: Bearer {YOUR_TOKEN_HERE}

Important

Be sure there is a one space between Bearer and {YOUR_TOKEN_HERE}

If you are already familiar with our platform, you can obtain your API token by visiting the Screening Service Web portal. Detailed instructions on finding your token are available in our documentation.

If you are new to our platform, please contact our team at sales@idscan.net to get started, or reach out to support@idscan.net with any questions.

Request Data

Here is a JSON request data example:

{
  "dateOfBirths": "1989-12-24",
  "issuedBy": "PE",
  "services": [
    "58B76696-75E2-466F-97A2-1B216ED40108"
  ],
  "driverLicenseNumber": "421450",
  "driverLicenseClass": "1",
  "metadata": {
    "myOwnRequestId": "qw-12345"
  }
}

Request fields description

Field Name	Required	Type	Possible Values
"dateOfBirths"	Yes	String	Date string in yyyy-MM-dd format
"issuedBy"	Yes	String	Two-letter province/territory code (e.g., PE, ON, BC)
"services"	Yes	Array[string]	Must contain exactly: "58B76696-75E2-466F-97A2-1B216ED40108"
"driverLicenseNumber"	Yes	String	Document number as issued by the province
"driverLicenseClass"	No	String	Up to 2 characters (one class per verification)
"metadata"	No	Object	Custom key-value pairs for your tracking (e.g., "myOwnRequestId": "qw-12345"). See the details here

Important

When the "services" field is null or is an empty array all the services your account has enabled will run. We do not recommend submitting request in this way. We recommend being explicit about which services you would like to run.

Response Data

Here is the JSON response example for the request above:

[
  {
    "serviceId": "58b76696-75e2-466f-97a2-1b216ed40108",
    "serviceName": "Canadian DMV Verification",
    "serviceDescription": "Canadian Driver License Data Verification",
    "error": null,
    "success": true,
    "locationId": null,
    "readOnlyAccessLocationIds": null,
    "metadata": {
      "myOwnRequestId": "qw-12345"
    },
    "profiles": [
      {
        "internalId": null,
        "firstName": "",
        "middleName": "",
        "lastName": "",
        "fullName": "",
        "dateOfBirths": "12/24/1989",
        "sex": null,
        "address": null,
        "countryName": null,
        "countryCode": null,
        "street1": null,
        "street2": null,
        "city": null,
        "state": null,
        "zipCode": null,
        "county": null,
        "convictiontype": null,
        "aliases": null,
        "offenses": null,
        "photoUrl": null,
        "source": null,
        "otherInformation": null,
        "idNumber": "421450",
        "issuedBy": "PE",
        "verificationResult": null,
        "driverLicenseVerificationResult": null,
        "canadianDriverLicenseVerificationResult": {
          "licenseVerificationResult": {
            "status": "Valid",
            "code": 1,
            "message": "Driver's license is valid"
          },
          "licenseClassVerificationStatus": "Class Match",
          "currentLicenseClasses": "1,3,5"
        }
      }
    ]
  }
]

Response fields description

A successful verification returns a response containing service information and a profile object. Note, the metadata field from your request is echoed back in the response (see the details here). Since this service uses a few fields, all non-used fields will be null or empty string value.

In general, "Profiles" is an array of profile's objects. But for Canadian DMV Service "Profiles" array contains just a single "Profile" object.

Profile object contains the fields from your request, such as dateOfBirths, issuedBy, etc., and includes a canadianDriverLicenseVerificationResult object with the service check results.
CanadianDriverLicenseVerificationResult object contains licenseVerificationResult object with three fields inside: status (string), code (int) and message (string). There are possible values for each:

Status	Code	Message
Not Completed	0	-
Valid	1	Driver's license is valid
Not Valid	2	Driver's license is suspended, cancelled or expired
Not Found	3	Driver's license is not found in the Jurisdiction
Invalid DOB	4	Driver's license is found in the Jurisdiction, but DOB is not match
Interlock	5	Driver’s license has an Ignition Interlock condition. The driver must only drive vehicles that are equipped with an approved Ignition Interlock device

licenseClassVerificationStatus (string) contains the verification status of the license class, if provided in the request. Possible values include: "Class Match", "N/A" (if class was not provided in the request), "Class Match/GDL", "Downgraded", "Learner", "Invalid Class", etc.
currentLicenseClasses (string) contains comma-separated license classes that match the requested driver's license.

Important

Billable verification requests are those that return codes 1 through 5. Code 0 (Not Completed) does not count against your subscription quota. If you receive Not Completed status, please try again after 15 min.

CURL request

You can also test the service via CURL. Here is an example:

curl -X POST https://screening.idscan.net/api/Check -H "Content-Type: application/json" -H "Authorization: Bearer YOUR-TOKEN-HERE" -d "{\"dateOfBirths\": \"1989-12-24\",\"issuedBy\": \"PE\",\"services\": [\"58B76696-75E2-466F-97A2-1B216ED40108\"],\"driverLicenseNumber\": \"421450\",\"driverLicenseClass\": \"1\"}"

Test cases

You can test and receive all license verification statuses from 1 to 5 with your TEST token. You can find test cases here

Error handling

Sometimes something went wrong and it's good to know what and how to deal with it. Common errors are described here. Additional errors are returned from this service are described here.