Trusona ID Proofing Service

1. Overview

Trusona AAMVA ID verification and anti-replay service.

1.1. Version information

Version : 2.0

2. Paths

2.1. Provides an endpoint to check API status

GET /api/v2/status

2.1.1. Responses

HTTP Code Description Schema
200 The current API status Response 200

Response 200

Name Schema
success
optional
string

2.1.2. Produces

  • application/json

2.2. Provides information about states participating in the AAMVA verification program.

GET /api/v2/supported_states

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

2.2.2. Produces

  • application/json

2.2.3. Example HTTP response

2.2.3.1. 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"
      } ]
    }
  }
}

2.3. Verifies an AAMVA identity document

POST /api/v2/verifications

2.3.1. Description

Forwards identity document information to the AAMVA service to check for matches on each field and analyzes anti-replay data to determine if this request has been seen before.

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

Transformation indicator: Yes
Character length: 1-255
PII: Yes
Data classification: Restricted
string
address_delivery_point_text_2
optional
street address 2

Transformation indicator: Yes
Character length: 1-255
PII: Yes
Data classification: Restricted
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

Transformation indicator: No
Character length: 1
PII: No
Data classification: Confidential
string
drivers_license_expiration_date
optional
A date a credential expires in the format of YYYYMMDD.

Transformation indicator: No
Character length: 8
PII: Yes
Data classification: Restricted
string (date)
drivers_license_issue_date
optional
A date a credential was issued in the format
of YYYYMMDD.

Transformation indicator: No
Character length: 8
PII: Yes
Data classification: Restricted
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”.

Transformation indicator: Yes
Character length: N/A
PII: Yes
Data classification: Restricted
string
location_city_name
optional
A name of a city or town.

Transformation indicator: Yes
Character length: 1-255
PII: Yes
Data classification: Restricted
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”.

Transformation indicator: No
Character length: 1-255
PII: Yes
Data classification: Restricted
string
location_state_us_postal_service_code
optional
A state, commonwealth, province, or other such geopolitical subdivision of a country.

Transformation indicator: No
Character length: 2
PII: Yes
Data classification: Restricted
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.

Transformation indicator: No
Character length: 2
PII: Yes
Data classification: Restricted
string
person_birth_date
optional
A date a person was born in the format of YYYYMMDD.

Transformation indicator: No
Character length: 8
PII: Yes
Data classification: Restricted
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/)

Transformation indicator: No
Character length: 3
PII: Yes
Data classification: Restricted
string
person_given_name
optional
A first name of a person.

Transformation indicator: No
Character length: 1-255
PII: Yes
Data classification: Restricted
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”

Transformation indicator: No
Character length: 3
PII: Yes
Data classification: Restricted
integer
person_middle_name
optional
A middle name of a person.

Transformation indicator: No
Character length: 1-255
PII: Yes
Data classification: Restricted
string
person_name_suffix_text
optional
A term appended after the family name that qualifies the name. (e.g. “Jr”)

Transformation indicator: No
Character length: 1-255
PII: Yes
Data classification: Restricted
string
person_sex_code
optional
A code identifying the sex of a person. The values are:
1 = Male
2 = Female

Transformation indicator: No
Character length: 1
PII: Yes
Data classification: Restricted
string
person_sur_name
optional
A last name or family name of a person.

Transformation indicator: No
Character length: 1-255
PII: Yes
Data classification: Restricted
string
person_weight_measure
optional
A measurement of a person’s weight in pounds. For example 195 pounds is encoded as “195”

Transformation indicator: No
Character length: 2-4
PII: Yes
Data classification: Restricted
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.

Transformation indicator: No
Character length: 1-255
PII: No
Data classification: Confidential
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

2.3.3. Responses

HTTP Code Description Schema
201 The verification was successfully created Response 201
400 Invalid JSON data was provided No Content
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

2.3.4. Consumes

  • application/json

2.3.5. Produces

  • application/json

2.3.6. Example HTTP response

2.3.6.1. Response 422
{
  "errors" : {
    "message_destination_id" : [ "can't be blank", "XX is not a supported state" ],
    "identification_id" : [ "can't be blank", "not suppported within cert environment" ],
    "checksum" : [ "Supplied checksum is incorrect" ],
    "transaction_locator_id" : [ "has already been taken" ]
  },
  "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"
    } ]
  }
}

2.4. Look up a verification record by the transaction locator ID.

GET /api/v2/verifications/{transaction_locator_id}

2.4.1. Parameters

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

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

2.4.3. Produces

  • application/json

2.4.4. Example HTTP response

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

3. Definitions

3.1. DowntimeWindow

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

4. Security

4.1. Bearer

Type : apiKey Name : Authorization In : HEADER


Integrations

Desktop
IAM and SSO
PAM
Productivity
RADIUS
VPN

Guides

Get started guides
Implementation guides
Users guides

SDKs

Mobile SDKs
Server SDKs
Web SDKs

APIs

Authentication Service
ID Proofing Service

TOTP

Business
E-commerce
Finance
Productivity
Social
Gaming
Other