Trusona DL Verification Service

What’s in this doc

Overview

Trusona AAMVA ID verification and anti-replay service.

Version information

Version : 1.3.0

Paths

Provides information about states participating in the AAMVA verification program.

GET /api/v1/supported_states

Responses

HTTP Code Description Schema
200 The states participating in the AAMVA program and their documented, scheduled downtimes for each day of the week. < string, Response 200 > map
403 Either the API key was not provided or it was invalid. No Content
500 An internal server error occurred. No Content

Response 200

Name Schema
downtime
optional
downtime

downtime

Name Schema
Friday
optional
< DowntimeWindow > array
Monday
optional
< DowntimeWindow > array
Saturday
optional
< DowntimeWindow > array
Sunday
optional
< DowntimeWindow > array
Thursday
optional
< DowntimeWindow > array
Tuesday
optional
< DowntimeWindow > array
Wednesday
optional
< DowntimeWindow > array

Produces

  • application/json

Example HTTP response

Response 200
{
  "AZ" : {
    "downtime" : {
      "Sunday" : [ {
        "start" : "02:00 ET",
        "end" : "05:00 ET"
      } ],
      "Monday" : [ ],
      "Tuesday" : [ ],
      "Wednesday" : [ ],
      "Thursday" : [ ],
      "Friday" : [ ],
      "Saturday" : [ ]
    }
  },
  "MD" : {
    "downtime" : {
      "Sunday" : [ {
        "start" : "01:00 ET",
        "end" : "05:00 ET"
      }, {
        "start" : "06:00 ET",
        "end" : "14:00 ET"
      } ],
      "Monday" : [ {
        "start" : "01:00 ET",
        "end" : "04:00 ET"
      } ],
      "Tuesday" : [ {
        "start" : "01:00 ET",
        "end" : "04:00 ET"
      } ],
      "Wednesday" : [ {
        "start" : "01:00 ET",
        "end" : "04:00 ET"
      } ],
      "Thursday" : [ {
        "start" : "01:00 ET",
        "end" : "04:00 ET"
      } ],
      "Friday" : [ {
        "start" : "01:00 ET",
        "end" : "04:00 ET"
      } ],
      "Saturday" : [ {
        "start" : "01:00 ET",
        "end" : "04:00 ET"
      } ]
    }
  }
}

Verifies an AAMVA identity document

POST /api/v1/verifications

Parameters

Type Name Description Schema
Body body
optional
Identity document data for verification. body

body

Name Schema
aamva
required
aamva
anti_replay
required
anti_replay

aamva

Name Description Schema
address_delivery_point_text_1
optional
street address 1 string
address_delivery_point_text_2
optional
street address 2 string
document_category_code
optional
A coded categorization of a state document issued by a jurisdiction to an individual (i.e. License, Permit, ID Card).

For a driver license the code is not required but may be included. For other types of documents it must be included.

The values are:
1 = Driver License
2 = Driver Permit
3 = ID Card
string
drivers_license_expiration_date
optional
A date a credential expires in the format of YYYYMMDD. string (date)
drivers_license_issue_date
optional
A date a credential was issued in the format
of YYYYMMDD.
string (date)
identification_id
required
An identifier of the License or Card (aka. Driver License Number).

Matching is not case sensitive, so a number will match if it is entered as “A123” or “a123”.
string
location_city_name
optional
A name of a city or town. string
location_postal_code
optional
An identifier of a post office-assigned zone for an address.

Include the ZIP code on the credential. A 5 digit code should be presented as “12345” and a 9 digit code as “123456789”.
string
location_state_us_postal_service_code
optional
A state, commonwealth, province, or other such geopolitical subdivision of a country. string
message_destination_id
required
An identifier of the jurisdiction which issues a person’s driving privileges.

This element is the two letter state code defined by the USPS.
string
person_birth_date
optional
A date a person was born in the format of YYYYMMDD. string (date)
person_eye_color_code
optional
A code identifying the eye color of a person.
The values are:
BLK = Black
BLU = Blue
BRO = Brown
DIC = Dichromatic
GRY = Gray
GRN = Green
HAZ = Hazel
MAR = Maroon
PNK = Pink

From the ANSI D20 standard. (https://www.aamva.org/D20/)
string
person_given_name
optional
A first name of a person. string
person_height_measure
optional
A measurement of a person’s height.

The height is provided in feet-inches. For example 5 foot 10 inches is encoded as “510”
integer
person_middle_name
optional
A middle name of a person. string
person_name_suffix_text
optional
A term appended after the family name that qualifies the name. (e.g. “Jr”) string
person_sex_code
optional
A code identifying the sex of a person. The values are:
1 = Male
2 = Female
string
person_sur_name
optional
A last name or family name of a person. string
person_weight_measure
optional
A measurement of a person’s weight in pounds. For example 195 pounds is encoded as “195” integer
transaction_locator_id
optional
An optional ID to use for tracking this request. If not provided, one will be generated. It must be unique. string

anti_replay

Name Schema
accel_x
optional
string
accel_y
optional
string
accel_z
optional
string
checksum
required
string
gyro_x
optional
string
gyro_y
optional
string
gyro_z
optional
string
nonce
required
string
scan_height
optional
string
scan_width
optional
string
scan_x
optional
string
scan_y
optional
string
timestamp
required
string

Responses

HTTP Code Description Schema
201 The verification was successfully created Response 201
403 Either the API key was not provided or it was invalid. No Content
422 Unable to process the request due to validation errors. Response 422
500 An internal server error occurred. No Content

Response 201

Name Description Schema
address_city_match_indicator
optional
  boolean
address_line1_match_indicator
optional
  boolean
address_line2_match_indicator
optional
  boolean
address_state_code_match_indicator
optional
  boolean
address_zip4_match_indicator
optional
  boolean
address_zip5_match_indicator
optional
  boolean
document_category_match_indicator
optional
  boolean
drivers_license_expiration_date_match_indicator
optional
  boolean
drivers_license_issue_date_match_indicator
optional
  boolean
drivers_license_number_match_indicator
required
  boolean
person_birth_date_match_indicator
optional
  boolean
person_eye_color_match_indicator
optional
  boolean
person_first_name_exact_match_indicator
optional
  boolean
person_first_name_fuzzy_alternate_match_indicator
optional
An indication of a fuzzy match on the first name. The alternate fuzzy match is for a compare of the alternate keys from the first names.

This element is returned when the exact match indicator for the First Name indicates a mismatch.

A value of true, is an indication of a loose match on the first name.
boolean
person_first_name_fuzzy_primary_match_indicator
optional
An indication of a fuzzy match on the first name. The primary fuzzy match is for a compare of the primary keys from the first names.

This element is returned when the exact match indicator for the First Name indicates a mismatch.

A value of true, is an indication of a strong match on the first name.
boolean
person_height_match_indicator
optional
  boolean
person_last_name_exact_match_indicator
optional
  boolean
person_last_name_fuzzy_alternate_match_indicator
optional
An indication of a fuzzy match on the last name. The alternate fuzzy match is for a compare of the alternate keys from the last names.

This element is returned when the exact match indicator for the Last Name indicates a mismatch.

A value of true, is an indication of a loose match on the last name.
boolean
person_last_name_fuzzy_primary_match_indicator
optional
An indication of a fuzzy match on the last name supplied by the user and the last name supplied by the state.

This element is returned when the exact match indicator for the Last Name indicates a mismatch, to show if the supplied name is similar to the name on record.

Double Metaphone is used to create keys for the fuzzy matching. The last name primary fuzzy match is for a compare of the primary keys from the last names.

A value of true, is an indication of a strong match on the last name.
boolean
person_middle_initial_match_indicator
optional
  boolean
person_middle_name_exact_match_indicator
optional
  boolean
person_middle_name_fuzzy_alternate_match_indicator
optional
An indication of a fuzzy match on the middle name. The alternate fuzzy match is for a compare of the alternate keys from the middle names.

This element is returned when the exact match indicator for the Middle Name indicates a mismatch.

A value of true, is an indication of a loose match on the middle name.
boolean
person_middle_name_fuzzy_primary_match_indicator
optional
An indication of a fuzzy match on the middle name. The primary fuzzy match is for a compare of the primary keys from the middle names.

This element is returned when the exact match indicator for the Middle Name indicates a mismatch.

A value of true, is an indication of a strong match on the middle name.
boolean
person_name_suffix_match_indicator
optional
  boolean
person_sex_code_match_indicator
optional
  boolean
person_weight_match_indicator
optional
  boolean
replay
optional
  boolean
transaction_locator_id
required
  string

Response 422

Name Description Schema
aamva_error
optional
An error occurred with the request sent to AAMVA aamva_error
errors
optional
Validation errors in the aamva portion of the request. < string, < string > array > map

aamva_error

Name Description Schema
details
optional
If provided by AAMVA, the list of error codes and messages. < details > array
message
optional
A generic description of the error that occurred. string

details

Name Description Schema
exception_actor_text
optional
The Exception Actor Text contains the description of the actor that raised the exception. string
exception_id
optional
An identification of an individual issue. string
exception_text
optional
  string

Consumes

  • application/json

Produces

  • application/json

Example HTTP response

Response 422
{
  "errors" : {
    "message_destination_id" : [ "can't be blank", "XX is not a supported state" ],
    "identification_id" : [ "can't be blank" ]
  },
  "aamva_error" : {
    "message" : "DLDV VSS - ExceptionId: 0019, ExceptionText: User not Authorized to send requests to MVA, ExceptionTypeCode: I, ExceptionFatalIndicatorCode: true, ExceptionActorText: AAMVA ESB Message Broker",
    "details" : [ {
      "exception_id" : "0001",
      "exception_text" : "Destination's connection is not active",
      "exception_actor_text" : "AAMVA NCS"
    }, {
      "exception_id" : "0001 or 0009",
      "exception_text" : "MVA system is unavailable",
      "exception_actor_text" : "MVA"
    }, {
      "exception_id" : "0002",
      "exception_text" : "MVA system error",
      "exception_actor_text" : "MVA"
    }, {
      "exception_id" : "0017",
      "exception_text" : "User not authorized to use this endpoint of the service",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "0018",
      "exception_text" : "Destination's connection is not active",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "0019",
      "exception_text" : "User not Authorized to send requests to MVA",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "0026",
      "exception_text" : "Origin Site Not Participating",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "0047",
      "exception_text" : "MVA did not respond in a timely fashion",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "0076",
      "exception_text" : "AAMVA System error",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "3401",
      "exception_text" : "Driver License ID is required",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "9925",
      "exception_text" : "Destination of the request is missing the Destination SiteID",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "9926",
      "exception_text" : "Origin of the request is missing the Origin SiteID",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "9995",
      "exception_text" : "TransactionLocatorID of the request is missing or invalid",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "9999",
      "exception_text" : "Unable to complete transaction, please contact AAMVA",
      "exception_actor_text" : "DLDV VSS"
    }, {
      "exception_id" : "X001",
      "exception_text" : "Invalid Authentication Token Provided",
      "exception_actor_text" : "AAMVA Authentication"
    } ]
  }
}

Look up a verification record by the transaction locator ID.

GET /api/v1/verifications/{transaction_locator_id}

Parameters

Type Name Description Schema
Path transaction_locator_id
required
The transaction locator ID of the verification request to look up. string

Responses

HTTP Code Description Schema
200 If the verification request was received, the transaction locator ID and the time it was created are returned. Response 200
403 Either the API key was not provided or it was invalid. No Content
404 The verification request for the given transaction locator ID was not received. No Content
500 An internal server error occurred. No Content

Response 200

Name Schema
created_at
required
string (date)
transaction_locator_id
required
string

Produces

  • application/json

Example HTTP response

Response 200
{
  "transaction_locator_id" : "2AB2AE59-4E28-4E3A-9480-57B19E09BBAD",
  "created_at" : "2019-03-20T16:47:58.520Z"
}

Definitions

DowntimeWindow

Name Schema
end
optional
string (time [HH:mm tz])
start
optional
string (time [HH:mm tz])

Security

Bearer

Type : apiKey Name : Authorization In : HEADER