MLA API

The MLA API provides programmatic access to perform MLA Active Duty status verification. The API is a real-time wrapper of the MLA website. The intended usage targets automated status verification in consumer credit transactions where near real-time response is required. The REST API allows for search submission using BASIC or API Key authentication. Xml and JSON formats are supported.

Overview

Below are the relevant topics to get you using the MLA REST API as quickly as possible:

POST Order

Places MLA search order. Order is processed and product can be retrieved using Pop. Automatically normalizes and generate name variations from last name when name suffixes or multiple name parts are supplied.

Resource Url

https://mla.quandis.com/Military/MLA.ashx/Order

Resource Information

Response Format JSON, Xml
Authentication Required Yes
Rate Limited No

HTTP Headers

X-ApiKey {Provided by Quandis}
Content-type application/x-www-form-urlencoded

Parameters

Parameter Description Required Type Example
FirstName First name of subject Optional String (50) John
MiddleName Middle name of subject Optional String (50) Michael
LastName Last name of subject Required String (255) Doe
USSSN Social Security Number of subject Required SSN 123456789
BirthDate Subject date of birth Required Date (MM/DD/YYYY) 01/15/1975
Reference Client reference number associated with search. We suggest using a unique value Required String (100) 456456-a
Output Sets response format. Possible values: Json, Xml. Xml is default format when unspecified. Optional Enumerated Json
IncludeCertificate When set to true, MLA certificates will be embedded as Base64 format. When set to false, certificates content is omitted in the product response. Certificate content will not be included in the response by default. Optional bool true
DirectPickup Utilized for Direct Product Pickup. When set to true, orders are routed for direct pickup bypassing Pop mechanism. Value defaults to false. Optional bool true
ForceSubmission When set to true, orders can be submitted regardless of DMDC MLA status and will be processed as soon as DMDC is online. Value defaults to false. Optional bool true

Parameter Validation

Required parameters are validated. Common validation failures are:

  • Invalid USSSN
  • Invalid birth date
  • Missing last name

When a validation exception occurs, the MLA API will return an HTTP 422 response code. The body of the HTTP 422 message will contain:

{
  "MLAResponse": {
    "@QuandisOrderID":"1",
    "Status":"Validation Error",
    "Exceptions": {
      "Exception": {
        "Type":
        "Data Validation",
        "Severity":"Error",
        "Message":"Invalid USSSN"
      }
    }
  }
}

Example Request

POST   /Military/MLA.ashx/Order HTTP/1.1
Content-type: application/x-www-form-urlencoded
LastName=Doe&FirstName=John&USSSN=555441212&BirthDate=01/01/1976&Reference=12345-a&Output=Json

Example Order Response JSON

{ 
  "MLAOrderResponse": { 
    "@QuandisOrderID": "1",
    "SourceReferenceNumber":"12345",
"Status": "Order Received" } }

GET Pop

Used to retrieve product data. Orders that are pending pickup are embedded as messages in the response. Each embedded order is automatically removed from the list and will no longer be present in subsequent calls. Message list is FIFO based.

Resource Url

https://mla.quandis.com/Military/MLA.ashx/Pop

Resource Information

Response Format JSON, Xml
Authentication Required Yes
Rate Limited No

HTTP Headers

X-ApiKey {Provided by Quandis}
Content-type application/x-www-form-urlencoded

Parameters

Parameter Description Required Example
Output Sets response format. Possible values: Json, Xml. Xml is default format when unspecified. Optional Json
MessageCount Allows for multiple messages to be downloaded at once. Allowed values: 1-5. Default value is 1 which implies one message will be returned when the pickup endpoint is invoked. Optional 1
PayloadType Embeds product content or product pointer in pickup message. Enumerated: Content, ResourceUrn. Default is Content. See below for best practices. Optional Content

Example Request

GET   /Military/MLA.ashx/Pop HTTP/1.1
Content-type: application/x-www-form-urlencoded
Output=Json

Example Response JSON

{ 
  "Messages": { 
    "@AvailableCount": "1", 
    "Message": [{ 
      "@ID": "6ad37a5c-1926-e811-9407-90b11c2ac2c", 
     "MLAResponse": { 
    "@QuandisOrderID": "2",
    "SourceReferenceNumber": "12345", 
    "Status": "Success", 
    "Contacts": { 
      "@Score": "Inactive", 
      "Contact": [{ 
        "LastName": "DOE", 
        "MLAResult": { 
          "Status": "Inactive", 
          "DateOfMatch": "2018-03-01", 
          "MatchResultCode": "No Match", 
          "CertificateID": "Z0ICFD01M0ADJ70" 
        }]
       }
     }] 
    } 
  }

Pop Best Practices
The frequency is which to invoke the Pop method should be set by a schedule in accordance with given SLA requirements. Since Pop is a polling method, it will return a message list with a count ranging from zero to the number of available messages. The following table is suggests best practices for invoking the Pop endpoint:

Message Count Returned Frequency
0 If no messages are available, use the next run date on the predefined schedule performing the polling.
Greater than 0 If messages are available, invoke the pickup method as soon as the previous call completes and repeat until no messages are available to ensure all messages are retrieved.

The Pop response allows for embedding of product data as a convenience or emitting a ResourceUrn which allows product to be accessed in a subsequent call. PayloadType usage guidelines are:

Payload Type Recommended Usage
Content (Embedded Product) Smaller payloads, smaller volume and when content is NOT processed during the pickup call. We recommend saving a copy of the content and processing at a later time.
ResourceUrn (Product Pointer) Larger payloads (due to multiple searches), larger volume with ability to use separate process to invoke the Product endpoint to download and process product a separate process. Also note the product can be obtained subsequent times by accessing ResourceUrn without invoking pickup method.

Practical Example: We suggest not to set MessageCount to 5 with PayloadType to Content and process data (saving file content, saving data to DBMS) during the pickup call in favor of MessageCount to 5 with PayloadType to ResourceUrn with separate calls to the product resource.

GET Product

Used to retrieve product data on an individual order basis. When utilizing this method, order requests must contain parameter DirectPickup set to true.

Resource Url

https://mla.quandis.com/Military/MLA.ashx/Product
ID=123&Output=Json

Resource Information

Response Format JSON, Xml
Authentication Required Yes
Rate Limited No

HTTP Headers

X-ApiKey {Provided by Quandis}
Content-type application/x-www-form-urlencoded

Parameters

Parameter Description Required Example
Output Sets response format. Possible values: Json, Xml. Xml is default format when unspecified. Optional Json
ID Quandis unique order identifier returned as QuandisOrderID when placing order. Required 1

HTTP Status Codes

Order Status HTTP Status
Complete 200
Incomplete 417

Example Response JSON (complete orders)

{ 
     "MLAResponse": { 
    "@QuandisOrderID": "2",
    "SourceReferenceNumber": "12345", 
    "Status": "Success", 
    "Contacts": { 
      "@Score": "Inactive", 
      "Contact": [{ 
        "LastName": "DOE", 
        "MLAResult": { 
          "Status": "Inactive", 
          "DateOfMatch": "2018-03-01", 
          "MatchResultCode": "No Match", 
          "CertificateID": "Z0ICFD01M0ADJ70" 
        }]
     }
  }

Example Response JSON (incomplete orders)

{"MLAResponse":{"@QuandisOrderID":"1","Status":"Unavailable"}}

POST Search

As of 3/16/2018 Quandis has disabled this method and advise using Order as an alternate. Quandis is continuing to evaluate technical options and in the interim will retain documentation on this method.

Performs MLA search for subject provided. Automatically normalizes and generate name variations from last name when name suffixes or multiple name parts are supplied.

Resource Url

https://mla.quandis.com/Military/MLA.ashx/Search

Resource Information

Response Format JSON, Xml
Authentication Required Yes
Rate Limited Yes

HTTP Headers

X-ApiKey {Provided by Quandis}
Content-type application/x-www-form-urlencoded

Parameters

Parameter Description Required Example
FirstName First name of subject Optional John
MiddleName Middle name of subject Optional Michael
LastName Last name of subject Required Doe
USSSN Social Security Number of subject Required 123456789
BirthDate Subject date of birth Required 01/15/1975
Reference Client reference number associated with search. We suggest using a unique value Required 456456-a
Output Sets response format. Possible values: Json, Xml. Xml is default format when unspecified. Optional Json
IncludeCertificate When set to true, MLA certificates will be embedded as Base64 format. When set to false, certificates content is omitted in the product response. Certificate content will not be included in the response by default. Optional true

Parameter Validation

Required parameters are validated. Common validation failures are:

  • Invalid USSSN
  • Invalid birth date
  • Missing last name

When a validation exception occurs, the MLA API will return an HTTP 422 response code. The body of the HTTP 422 message will contain:

{
  "MLAResponse": {
    "@QuandisOrderID":"1",
    "Status":"Validation Error",
    "Exceptions": {
      "Exception": {
        "Type":
        "Data Validation",
        "Severity":"Error",
        "Message":"Invalid USSSN"
      }
    }
  }
}

Example Request

POST   /Military/MLA.ashx/Search HTTP/1.1
Content-type: application/x-www-form-urlencoded
LastName=Doe&FirstName=John&USSSN=555441212&BirthDate=01/01/1976&Reference=12345-a&Output=Json

Example Response JSON

{ 
  "MLAResponse": { 
    "@QuandisOrderID": "2", 
    "Status": "Success", 
    "Contacts": { 
      "@Score": "Inactive", 
      "Contact": [
       { 
        "LastName": "DOE", 
        "MLAResult": { 
          "Status": "Inactive", 
          "DateOfMatch": "2016-05-18", 
          "MatchResultCode": "No Match", 
          "CertificateID": "Z0ICFD01M0ADJ70" 
        } 
      }
     ] 
    } 
  } 
}

Response Data Points

Parent Data Point  Description
MLAResponse @QuandisOrderID Quandis issued unique, numerical order identifier.
Contacts @Score Status roll-up based of one to many searches associated with the request.  Possible values: Active | Inactive. When multiple searches are performed, any individual search with status of Active will set score to Active.
Contact Contact Parent data point of individual search. Repeatable based on number of individual searches performed as part of request.
Contact LastName Last name of subject searched.
Contact MiddleName Middle name of subject searched.
Contact FirstName First name of subject searched.
MLAResult Status Indicates if subject was on active duty on the date the search was performed. Possible values: Active | Inactive. Active indicates subject is on Active Duty as of the search date or is a dependent of a Service member on Active Duty as of the search date. Inactive indicates subject is not on Active Duty as of the search date and is not a dependent of a Service member on Active Duty as of the search date.
MLAResult DateOfMatch Used to record the date that DMDC completed the MLA match. It is effectively the “as of” date of the match. The current active duty status of Service members can and does change daily, so it’s important to record when the MLA match was completed.
MLAResult MatchResultCode Result of match indicated by matching subject against DMDC database. Possible values:

No Match Information provided failed to match to a Service member or dependent in our database
Match – SSN, Date of Birth, and Last Name Record match on SSN, Last Name, and Date of Birth.
Not Affiliated Individual Unable to determine that subject is or ever was affiliated with the uniformed services.
MLAResult CertificateID  Unique identifier for certificate issued as part of MLA check.
MLAResult Certificate Parent data point of embedded MLA certificate. Data point is only rendered when IncludeCertificate is set to true in request
Certificate FileName FileName of embedded certificate
Certificate Content Base64 content of MLA certificate

Authentication Models

MLA supports both API Key and Basic authentication. API Keys are associated with a user account, and recommended for automation. When you sign up, Quandis will provide credentials to access the system which include username, password and API Key.

API Key authentication requires a custom HTTP request header:

  • X-ApiKey:

Api Key is formatted as a GUID.

BASIC authentication requires the Authorization header to be set. Note that many programming languages will set this automatically by associating a credential with a HTTP request. HTTP Status 403 unauthorized will be returned if validation fails. The body of the HTTP 403 message will contain:

{
  "MLAResponse": {
    "Status":"Error",
    "Exceptions": {
      "Exception": {
        "Type":"Authetication",
        "Severity":"Error",
        "Message":"Unable to login using ApiKey 'x'. API Key is expired"
      }
    }
  }
}
  • Authorization: Basic <base64encode(username:password)></base64encode(username:password)>

Username and password are provided by Quandis and can also be used to log into the web portal. HTTP Status 401 unauthorized will be returned if validation fails.

API Rate Limits

Rate limits limit the amount of requests placed over a time period. Common examples of rate limits would be:

  • Account cannot place more than 30 requests per second
  • Account cannot place more than 15000 requests per hour

Rate limits are determined on a per account basis and established during sign-up.

When an application exceeds the rate limit, the MLA API will return an HTTP 429 response code. The body of the HTTP 429 message will contain:

{
  "MLAResponse": {
    "Status":"Error",
    "Exceptions": {
      "Exception": {
        "Type":"Rate Limit",
        "Severity":"Error",
        "Message":"Rate Limit Exceeded"
      }
    }
  }
}

MLA API Uptime

The MLA API is a real-time wrapper of the DMDC MLA website and requires the website to be online to fulfill orders. Quandis maintains a 99.9% website uptime against the DMDC MLA website. The DMDC MLA website will periodically go offline for maintenance. The maintenance schedule is fully dictated by DMDC, and generally occurs on weekend dates. DMDC provides advanced notice of maintenance windows, and Quandis users can subscribe to these notifications and plan accordingly.

Quandis monitors the DMDC MLA website uptime and can determine availability to process orders. When DMDC is unavailable, the MLA API will reject orders and return a HTTP 417 response code. The body of the HTTP 417 message will contain:

{
  "MLAOrderResponse":{
    "Exceptions":{"Exception":{
      "Type":"System.Exception","Severity":"Error","Message":"MLA Website detected as offline; Search will not be performed"
    }
  }
 }
}

The MLA API fulfills orders in 90 seconds (on average) under normal circumstances. When DMDC MLA is offline, Quandis is unable to meet this fulfillment time. Given the superset of MLA API consumer use cases, the API is used in an “interactive” scenario and it’s essential for clients to receive product under standard timelines. Quandis has recognized the importance providing this expectation to our clients during order placement. For clients that do not require an  interactive scenario, they can submit orders regardless of DMDC MLA status and Quandis will process when DMDC is back online.