Introduction
The Alabama Law Enforcement Agency (ALEA) in partnership with Tyler Technologies 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 This document provides a high-level overview on of implementing and interfacing with the new standard DMS interface for the state 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 of up to 12 months in the future. This will provide you with a monthly update for each of the months month 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.1240 / per month | Any portion of the start to end monitoring date period monitored date range which is prior to the end of the current month in which monitoring is originally requested. | Has Have 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 Scheduled monitoring | $0.12 40 / 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 monthScheduled monitoring for each future month individually. | 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
Environment | URL | Purpose |
---|
UAT | https://test.alabamainteractive.org/mvr_search/MonitoringWS.jws?wsdl | This is the WSDL, which defines the SOAP service and its available methods |
UAT | https://test.alabamainteractive.org/mvr_search/MonitoringWS.jws | This is the web service end-point and is where you will direct your requests |
Production | https://www.alabamainteractive.org/mvr_search/MonitoringWS.jws?wsdl | This is the WSDL, which defines the SOAP service and its available methods |
Production | https://www.alabamainteractive.org/mvr_search/MonitoringWS.jws | This is the web service end-point and is where you will direct your requests |
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 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 pastCannot be a future month- 12 months in the past
- Cannot be a future month
1Note: To correctly add monitoring for a single month, both the monitorStartDate and monitorEndDate values will be the same. 2Note: The monitoring start date includes the month provided. |
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
1Note: To correctly add monitoring for a single month, both the monitorStartDate and monitorEndDate values will be the same. 2Note: The monitoring end date includes the month provided. |
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 customer's system. This value will be used to make this record unique from other requests and as part of any duplicate checking if provided.
|
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 |
monitorId | Number |
|
|
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> |
Invalid monitoring end date | Invalid date range: Invalid date range: monitorEndDate. MonitorEndDate is less than MonitorStartDate. |
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 68780059 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 |
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 68780059 |
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 citation withdrawal is added to a record |
monitoringRequests.monitoringRequest.citationRemovedwithdrawalRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a citation withdrawal is removed from a record |
monitoringRequests.monitoringRequest.accidentAddedreinstated | 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 submitDriverMonitoringRequest or 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 simplicityPossible 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 68780059 or 68780059 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 the 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.
Driver Monitoring results are processed on the 2nd day of the month at 10:30 AM central. Records will be available shortly after this time, depending on processing time. An email will be sent to customers when processing is complete and records are officially available. These results are available without expiration for reporting and reconciliation purposes. However, once the "viewDriverMonitoringRecord" method for a given record has been requested and the MVR has been delivered, that MVR is only available for seven days from the time it is first delivered.
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
Field | Test Value | Notes |
---|
username | Your actual username |
|
password | Your actual password |
|
monitorMonth | 201701202401 | You can use other value to see a response that does not have results, but 201701 202401 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
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 68780059 |
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/falseIndicates if any of the requested triggers caused a HIT eventfalse | Indicates if any of the requested triggers caused a HIT event |
monitoringResults.monitoringResult.status | Number |
| Indicates if a record has been processed and if so what the result is. See the list of Monitoring Results Status Codes below. |
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 |
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.accidentRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when an accident is removed from a record |
monitoringResults.monitoringResult.withdrawalAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record |
monitoringResults.monitoringResult.withdrawalRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record |
monitoringResults.monitoringResult.reinstated | Boolean | true/false | A value indicating if 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.citationRemovedResult | Boolean | true/false | A value indicating if a citation is removed from a record. If you chose not to monitor based on this trigger, it will always be false |
monitoringResults.monitoringResult.accidentAddedResult | Boolean | true/false | A value indicating if a new accident is added to a record. If you chose not to monitor based on this trigger, it will always be false |
monitoringResults.monitoringResult.accidentRemovedResult | Boolean | true/false | A value indicating if a accident is removed from a record. If you chose not to monitor based on this trigger, it will always be false |
monitoringResults.monitoringResult.withdrawalAddedResult | Boolean | true/false | A value indicating if a new withdrawal is added to a record. If you chose not to monitor based on this trigger, it will always be false |
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 methodthe 68780059 method. Note that once the record has been requested and the MVR has been delivered, that MVR is only available for seven days from the time it is first delivered.
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 68780059 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 | Record Has Hit |
---|
5001 | 2000005 | No | 5002 | 2000006 | No | 5003 | 2000007 | Yes | 5004 | 2000008 | No | 5005 | 2000009 | Yes | 5006 | 2000010 | No | 5007 | 2000012 | Yes | 5008 | 2000013 | Yes |
|
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. |
© 2016 Alabama Interactive, LLC | 2000008 | No | 5005 | 2000009 | Yes | 5006 | 2000010 | No | 5007 | 2000012 | Yes | 5008 | 2000013 | Yes |
|
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. |
Monitoring Result Status Codes
Anchor |
---|
| MonitoringResultStatusCodes |
---|
| MonitoringResultStatusCodes |
---|
|
Value | Definition |
---|
1 | Requested - Record has been requested, but processing has not yet been completed. |
2 | No Changes Found - Record has been processed successfully and no changes to the record were found. |
3 | Changes Found - Record has been processed successfully and changes were found. You can retrieve the full record using the requestDriverMonitoringRecord method. |
4 | No Matching Record Found - No matching driver license record could be found. |
5 | Invalid License Number - The driver license number provided is not valid and no record could be found. |
6 | Unknown Error Occurred - An unexpected error occurred. |