Introduction
The Alabama Law Enforcement Agency (ALEA) in partnership with Alabama Interactive has developed a new secure method of monitoring driver record information. This service will allow authorized customers to monitor Alabama Driver History Records (DHRs) for changes such as traffic citations(s), accident record(s), administrative action(s) and status change(s). The system, called Driver Monitoring Service (DMS), will replace the existing monthly bulk data file, previously known as the pointer file, provided by ALEA commonly referred to as the "Pointer File". This document provides a high level overview on implementing and interfacing with the new standard DMS interface for the state of Alabama.
Acronyms
| DMS | Driver Monitoring Service |
|---|
| DHR | Driver History Record |
|---|
| HIT | Has Initiated Trigger |
|---|
| HTTPS | Secure Hypertext Transfer Protocol |
|---|
| XML | eXtended Markup Language |
|---|
| XSD | XML Schema Definition |
|---|
| ALEA | Alabama Law Enforcement Agency |
|---|
Usage Requirements
The DMS is developed as a SOAP web service. Customers will have the option to make requests to: add records to be monitored, list records being monitored, remove a record from monitoring, list monitoring results and request monitoring details for a specific record.
New Requests
New monitoring requests can be submitted with a start date up to 12 months in the past, which will trigger a HIT if any of the requested triggers are true from the provided start date to the end of the current monitoring month. A look back type request would typically be used as a one time history check for a new customer. To get monthly status information on a monitored record going forward you would submit your monitoring request with an end date up to 12 months in the future. This will provide you with a monthly update for each of the months included in your start to end date range.
Costs
Your customer account will be billed per monitoring request per the following fee schedule.
| Monitoring Request Type | Cost Per Request | Description | Example |
|---|
| Look back monitoring | $0.12 | Any portion of the start to end monitoring date period which is prior to the end of the month in which monitoring is originally requested. | Has there been any changes to this record in the past six months?
A record is requested to be added to monitoring in September with a monitoring start date of April and an end date of September. This request will look for any of the requested triggers in all six of those months as a single collective check. The monitoring result for this record will be provided to the customer at the beginning of October. |
| Look forward monitoring | $0.12 / per month | Any portion of the start to end monitoring date period which is after the end of the month in which monitoring is originally requested will be charged the per request rate for each month. | Let me know if there are any changes to this record over the next three months.
A record is requested to be added to monitoring in September with a monitoring start date of October and an end date of December. Each future month being monitored will be split into a unique monitoring request. This request will look for any of the requested triggers in each of the three months individually as they pass. The monitoring result for this record will be provided to the customer in November, December and January for October, November and December respectively. Your account will be billed at the per request rate in each of the three months being monitored. |
| Dual span monitoring | $0.12 for look back +
$0.12 / per future month | Any portion of the start to end monitoring date period which is prior to the end of the month in which monitoring is originally requested will be charged once at the per request rate.
Any portion of the start to end monitoring date period which is after the end of the month in which monitoring is originally requested will be charged the per request rate for each month. | Has there been any changes to this record in the past twelve months and let me know if there are any changes to this record over the next twelve months.
A record is requested to be added to monitoring in September with a monitoring start date of October of the previous year and an end date of September of the following year. A request which spans both past and future months will be split into two groups of requests; a look back request spanning from the monitoring start date to the end of the month the request was received in and a future request, which will be split into a unique monitoring request per future month being monitored. The monitoring result for this record will be provided to the customer at the beginning of October, to cover from the previous October until the end of September of the current year, as well as in each of the next twelve months for the future months being monitored. Your account will be billed once in September for the entirety of the look back request and then once in each of the twelve look forward months. |
Connection Strings
Web Service Method Definitions
submitDriverMonitoringRequest
| Anchor |
|---|
| submitDriverMonitoringRequest |
|---|
| submitDriverMonitoringRequest |
|---|
|
This is the method used to add new driver monitoring requests to your account.
Request
| Field | Required | Data Type | Format | Notes |
|---|
| username | Yes | String |
| The username in your customer account approved to request driver monitoring |
| password | Yes | String |
| The password associated with the provided username |
| dlNumber | Yes | String | - 7 or 8 digits
- "I" + 6 or 7 digits
- "ID" + 5 or 6 digits
| The driver license number to be monitored |
| monitorStartDate | Yes | Number | yyyymm | - 4-digit Year & 2-digit Month
- Can be no more than 12 months in the past
- Cannot be a future month
|
| monitorEndDate | Yes | Number | yyyymm | - 4-digit Year & 2-digit Month
- Can be no more than 12 months in the future
- Cannot be before the current month
|
| customerReferenceId | No | String | Max Length: 100 | This is an optional, but recommended field and should contain a unique identifier to tie this request back to the customers system.
This value is not used to make this record unique from other requests and not used as part of any duplicate checking.
|
| citationAdded | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new citation is added to a record |
| citationRemoved | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a citation is removed from a record |
| accidentAdded | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new accident is added to a record |
| accidentRemoved | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when an accident is removed from a record |
| withdrawalAdded | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record |
| withdrawalRemoved | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record |
| reinstated | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a license is reinstated |
Response
| Field | Data Type | Format | Notes |
|---|
| successfulResponse | Boolean | true/false | Indicates if the monitoring request was successfully added to your account |
| message | String |
| If successfulResponse = false, then an error message will be present. Otherwise, this value will be blank |
Possible Error Messages
| Reason | Error Message |
|---|
| Invalid monitoring start date format | Invalid format: monitorStartDate. |
| Invalid monitoring end date format | Invalid format: monitorEndDate. |
| Invalid monitoring start date | Invalid date range: monitorStartDate. monitorStartDate must be less than or equal to <current month yyyymm> |
| Invalid monitoring end date | Invalid date range: monitorEndDate. MonitorEndDate must be greater than or equal to <current month yyyymm> |
| Duplicate request found | Duplicate found |
viewDriverMonitoringRequests
| Anchor |
|---|
| viewDriverMonitoringRequests |
|---|
| viewDriverMonitoringRequests |
|---|
|
This method allows you to view the list of all pending driver monitoring requests within a given month. Note that only pending non-completed monitoring requests can be viewed from this method. To view completed monitoring results, see the viewDriverMonitoringResults method.
Request
| Field | Required | Data Type | Format | Notes |
|---|
| username | Yes | String |
| The username in your customer account approved to request driver monitoring |
| password | Yes | String |
| The password associated with the provided username |
| monitorMonth | Yes | Number | yyyymm | 4-digit Year & 2-digit Month |
Response
| Field | Data Type | Format | Notes |
|---|
| successfulResponse | Boolean | true/false | Indicates if the request returned a successful response |
| message | String |
| If successfulResponse = false, then an error message will be present. Otherwise, this value will be blank |
| monitorMonth | Number | yyyymm | This will be the monitor month provided in the request |
| monitoringRequests | Object List | monitoringRequest object | This will contain a list of monitoring request object |
| monitoringRequests.monitoringRequest | Object | monitoringRequest | This is a specific monitoring request and includes all of the fields provided when the request was added |
| monitoringRequests.monitoringRequest.monitorId | Number |
| This is the unique Monitoring ID for this monitored record |
| monitoringRequests.monitoringRequest.customerReferenceId | String |
| This is the value provided in the original submitDriverMonitoringRequest |
| monitoringRequests.monitoringRequest.dlNumber | String |
| The driver's license number being monitored |
| monitoringRequests.monitoringRequest.citationAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new citation is added to a record |
| monitoringRequests.monitoringRequest.citationRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a citation is removed from a record |
| monitoringRequests.monitoringRequest.accidentAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new accident is added to a record |
| monitoringRequests.monitoringRequest.accidentRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when an accident is removed from a record |
| monitoringRequests.monitoringRequest.withdrawalAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record |
| monitoringRequests.monitoringRequest.withdrawalRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record |
| monitoringRequests.monitoringRequest.reinstated | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a license is reinstated |
Possible Error Messages
| Reason | Error Message |
|---|
| Invalid monitor month format | Invalid format: monitorMonth (yyyyMM) |
removeDriverMonitoringRequest
Use this method to remove a monitoring request. Note that only pending non-completed monitoring requests can be removed.
Request
| Field | Required | Data Type | Format | Notes |
|---|
| username | Yes | String |
| The username in your customer account approved to request driver monitoring |
| password | Yes | String |
| The password associated with the provided username |
| monitorId | Yes | Number |
| This is the unique identifier provided in the viewDriverMonitoringRequests response and must be provided to confirm you are removing the intended record from monitoring. Note that only pending monitoring requests may be removed. Those which have already been completed and results provided will not be able to be removed. |
| dlNumber | Yes | String | - 7 or 8 digits
- "I" + 6 or 7 digits
- "ID" + 5 or 6 digits
| The driver's license number you would like to remove from monitoring |
| customerReferenceId | No | String |
| If provided will be used in combination with the monitorId and dlNumber to uniquely identify and remove the requested record from monitoring |
Response
| Field | Data Type | Format | Notes |
|---|
| successfulResponse | Boolean | true/false | Indicates if the request to remove the record from monitoring was successful |
| message | String |
| If successfulResponse = false, then an error message will be present. Otherwise, this value will be blank |
Possible Error Messages
| Reason | Error Message |
|---|
| Invalid request criteria | No records match the parameters provided |
| Invalid driver license format | Drivers License Number is invalid format |
viewDriverMonitoringResults
| Anchor |
|---|
| viewDriverMonitoringResults |
|---|
| viewDriverMonitoringResults |
|---|
|
This method allows you to view the list of all completed driver monitoring requests for a given month. This method will list all of the details of the original monitoring request including the triggers requested as well a true/false value indicating which trigger(s) caused a record HIT, if any. A single "recordHasHit" boolean value will also be sent for simplicity.
Request
| Field | Required | Data Type | Format | Notes |
|---|
| username | Yes | String |
| The username in your customer account approved to request driver monitoring |
| password | Yes | String |
| The password associated with the provided username |
| monitorMonth | Yes | Number | yyyymm | 4-digit Year & 2-digit Month |
Test Request
| Data Type | FormatsuccessfulResponse| monitoringResults.monitoringResult.citationRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a citation is removed from a record |
| monitoringResults.monitoringResult.accidentAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new accident is added to a record |
monitoringResults.monitoringResult.accidentRemovedBoolean | true/false | Indicates if the request returned a successful response | message | String | If successfulResponse = false, then an error message will be present. Otherwise, this value will be blank | | monitorMonth | Number | yyyymm | This will be the monitor month provided in the request |
| monitoringResults | Object List | monitoringResult object | This will contain a list of monitoring result object |
| monitoringResults.monitoringResult | Object | monitoringResult | This is a specific monitoring result and includes all of the fields provided when the request was added, as well as an indicator of whether this record triggered a HIT and individual indicators as to which event triggered the HIT |
monitoringResults.monitoringResult.monitorId | Number | This is the unique Monitoring ID for this monitored record | monitoringResults.monitoringResult.customerReferenceId | String | This is the value provided in the original submitDriverMonitoringRequest | monitoringResults.monitoringResult.dlNumber | String | The driver's license number being monitored | | monitoringResults.monitoringResult.monitorStart | Number | yyyymm | The start date this monitoring request applies to |
| monitoringResults.monitoringResult.monitorEnd | Number | yyyymm | The end date this monitoring request applies to |
| monitoringResults.monitoringResult.recordHasHit | Boolean | true/false | Indicates if any of the requested triggers caused a HIT event |
| monitoringResults.monitoringResult.citationAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new citation is added to a record |
| Your actual username |
|
| password | Your actual password |
|
| monitorMonth | 201701 | You can use other value to see a response that does not have results, but 201701 is the only one that will return a list of records. Keep in mind this is a canned list of records and will not correspond to the list you created using the submitDriverMonitoringRequest method in the test system. |
Response
viewDriverMonitoringRecord
This method will be used to request the full DHR for each record indicated as having a HIT in the viewDriverMonitoringResults method.
Request
| Field | Required | Data Type | Format | Notes |
|---|
username | Yes | String | The username in your customer account approved to request driver monitoring | password | Yes | String | The password associated with the provided username | monitorId | Yes | Number | This is the unique identifier provided in the viewDriverMonitoringResults response and must be provided to confirm you are requesting the desired DHR | dlNumber | Yes | String | This is the driver's license number of the monitoring request that had a HIT and is being requested to obtain the DHR| Field | Data Type | Format | Notes |
|---|
| successfulResponse | Boolean | true/false | Indicates if the request returned a successful response |
| message | String |
| If successfulResponse = false, then an error message will be present. Otherwise, this value will be blank |
| monitorMonth | Number | yyyymm | This will be the monitor month provided in the request |
| monitoringResults | Object List | monitoringResult object | This will contain a list of monitoring result object |
| monitoringResults.monitoringResult | Object | monitoringResult | This is a specific monitoring result and includes all of the fields provided when the request was added, as well as an indicator of whether this record triggered a HIT and individual indicators as to which event triggered the HIT |
| monitoringResults.monitoringResult.monitorId | Number |
| This is the unique Monitoring ID for this monitored record |
| monitoringResults.monitoringResult.customerReferenceId | String |
| This is the value provided in the original submitDriverMonitoringRequest |
| monitoringResults.monitoringResult.dlNumber | String |
| The driver's license number being monitored |
| monitoringResults.monitoringResult.monitorStart | Number | yyyymm | The start date this monitoring request applies to |
| monitoringResults.monitoringResult.monitorEnd | Number | yyyymm | The end date this monitoring request applies to |
| monitoringResults.monitoringResult.recordHasHit | Boolean | true/false | Indicates if any of the requested triggers caused a HIT event |
| monitoringResults.monitoringResult.citationAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when an accident is removed from a new citation is added to a record |
| monitoringResults.monitoringResult.withdrawalAddedcitationRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new withdrawal is added to citation is removed from a record |
| monitoringResults.monitoringResult.withdrawalRemovedaccidentAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a withdrawal is removed from new accident is added to a record |
| monitoringResults.monitoringResult.reinstatedaccidentRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a license is reinstatedan accident is removed from a record |
| monitoringResults.monitoringResult.citationAddedResultwithdrawalAdded | Boolean | true/false | A value indicating if if you wish to trigger monitoring hits when a new citation withdrawal is added to a record. If you chose not to monitor based on this trigger, it will always be false | monitoringResults.monitoringResult.citationRemovedResult | Boolean |
| monitoringResults.monitoringResult.withdrawalRemoved | Boolean | true/false | A value indicating if a citation you wish to trigger monitoring hits when a withdrawal is removed from a record. If you chose not to monitor based on this trigger, it will always be false |
| monitoringResults.monitoringResult.accidentAddedResultreinstated | Boolean | true/false | A value indicating if a new accident is added to a you wish to trigger monitoring hits when a license is reinstated |
| monitoringResults.monitoringResult.citationAddedResult | Boolean | true/false | A value indicating if a new citation is added to a record. If you chose not to monitor based on this trigger, it will always be false |
| monitoringResults.monitoringResult.accidentRemovedResultcitationRemovedResult | Boolean | true/false | A value indicating if a accident citation is removed from a record. If you chose not to monitor based on this trigger, it will always be false |
| monitoringResults.monitoringResult.withdrawalAddedResultaccidentAddedResult | Boolean | true/false | A value indicating if a new withdrawal accident is added to a record. If you chose not to monitor based on this trigger, it will always be false |
| monitoringResults.monitoringResult.withdrawalRemovedResultaccidentRemovedResult | Boolean | true/false | A value indicating if a withdrawal accident is removed from a record. If you chose not to monitor based on this trigger, it will always be false |
| monitoringResults.monitoringResult.reinstatedResultwithdrawalAddedResult | Boolean | true/false | A value indicating if the license is reinstateda new withdrawal is added to a record. If you chose not to monitor based on this trigger, it will always be false |
Possible Error Messages
| Reason | Error Message |
|---|
| Invalid monitor month format | Invalid format: monitorMonth (yyyyMM) |
| monitoringResults.monitoringResult.withdrawalRemovedResult | Boolean | true/false | A value indicating if a withdrawal is removed from a record. If you chose not to monitor based on this trigger, it will always be false |
| monitoringResults.monitoringResult.reinstatedResult | Boolean | true/false | A value indicating if the license is reinstated. If you chose not to monitor based on this trigger, it will always be false |
Possible Error Messages
| Reason | Error Message |
|---|
| Invalid monitor month format | Invalid format: monitorMonth (yyyyMM) |
viewDriverMonitoringRecord
This method will be used to request the full DHR for each record indicated as having a HIT in the viewDriverMonitoringResults method.
Request
| Field | Required | Data Type | Format | Notes |
|---|
| username | Yes | String |
| The username in your customer account approved to request driver monitoring |
| password | Yes | String |
| The password associated with the provided username |
| monitorId | Yes | Number |
| This is the unique identifier provided in the viewDriverMonitoringResults response and must be provided to confirm you are requesting the desired DHR |
| dlNumber | Yes | String |
| This is the driver's license number of the monitoring request that had a HIT and is being requested to obtain the DHR |
Test Request
| Field | Test Value | Notes |
|---|
| username | Your actual username |
|
| password | Your actual password |
|
| monitorId | Any value included in the viewDriverMonitoringResults method from the test system | Test Cases | Monitor ID | DL Number |
|---|
| 5001 | 2000005 | | 5002 | 2000006 | | 5003 | 2000007 | | 5004 | 2000008 | | 5005 | 2000009 | | 5006 | 2000010 | | 5007 | 2000012 | | 5008 | 2000013 |
|
| dlNumber | Any value included in the viewDriverMonitoringResults method from the test system |
Response
| Field | Data Type | Format | Notes |
|---|
| successfulResponse | Boolean | true/false | Indicates if the response includes the record requested |
| message | String |
| Will contain an error message if the request for the driving record is not successful |
| searchRespone | Object |
| This is the same format response returned by the existing Driver History web service. The details on formatting can be found here: Driver History web service integration guide |
Possible Error Messages
| Reason | Error Message |
|---|
| Invalid request criteria | No records match the parameters provided |
| Invalid driver license format | Drivers License Number is invalid format |
Standard Authentication Error Responses
| Reason | Error Message |
|---|
| Invalid Login | Invalid login for <username> |
| Invalid or no DPPA for user | Valid login for <username>, but DPPA Number is not valid. |
| User does not have any access permissions | Valid login for <username>, but login access group list is empty. |
| User does not have permission to access this service | Valid login for <username>, but DPS_MVR_PTP_WS access group may not be present. |
| Access not grated to UAT environment | Access to the test web service is only available for testing purposes. |