QMS API

The Quandis Military Search (QMS) API is based on RESTful principles, making it easy to integrate QMS functionality into your applications. With the API, you can initiate searches, fetch results, specify preferences for your account, and retrieve dashboard data for the searches you’ve performed.

Base URL

QMS offers both test and production websites. The base URL for each is:

  • UAT: https://uatscra.quandis.net/Military
  • Production: https://scra.quandis.net/Military

Authentication

QMS offers both forms-based and Basic authentication. The credentials you use are the same, whether you are using forms-based or Basic authentication. For automation, Basic authentication is recommended. When you sign up for QMS, Quandis will provide you with credentials (typically an email address and password). These credentials must be specified when making API calls.

Searching for Active Duty Status

To perform an active duty search, you will call Military.ashx/Search, posting the name, address and other contact information of the individual to be searched. QMS will return a unique identifier (ContactID) that you can use to retrieve the results.

Example request:

POST Military.ashx/Search HTTP/1.1
FirstName=John&LastName=Doe&USSSN=123456789

Example response:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
<ContactItem>
  <ContactID>987612345</ContactID>
</ContactItem>

Retrieving Search Results

To retrieve the search results, you will refer to the ContactID returned when you submitted your search.

Example request

GET Military.ashx/Response?ContactID=987612345 HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
<ContactCollection>
  <ContactItem>
    <Contact>Doe, John</Contact>
    <SCRAStatus>Active</SCRAStatus>
    <SCRAStatusAsOf>8/15/2014</SCRAStatusAsOf>
    <CertificateID>564738291</CertificateID>
  </ContactItem>
</ContactCollection>

Notes:

  • If permutations or SSN lookup options are enabled, the results will typically contain multiple <ContactItem/> nodes, one for each permutation or alias.
  • The CertificateID can be used to download the PDF certificate returned by DoD at any point in the future.

Retrieving Search Results with the PDF Certificate

In the example above, the response returned included a CertificateID that is a pointer to the PDF returned by the DoD. If you wish to retrieve the results with the PDF in the same transaction, specify an IncludeCertificate option.

To retrieve the search results, you will refer to the ContactID returned when you submitted your search.

Example request

GET Military.ashx/Response?ContactID=987612345&IncludeCertificate=true HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
<ContactCollection>
  <ContactItem>
    <Contact>Doe, John</Contact>
    <SCRAStatus>Active</SCRAStatus>
    <SCRAStatusAsOf>8/15/2014</SCRAStatusAsOf>
    <CertificateID>564738291</CertificateID>
    <CertificateContent><![CDATA[ { base64 encoded PDF content will be here } ]]>
  </ContactItem>
</ContactCollection>

Searching with a Callback URL

When performing a search, you may specify a callback URL. Once QMS completes the search, we will post the results (in either JSON or XML format) to this URL. This allows you to submit searches without ‘polling’ for responses.

Example request

POST Military.ashx/Search?Callback=https://acme.com/QMSResults.jsp HTTP/1.1
FirstName=John&LastName=Doe&USSSN=123456789

Example synchronous response:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
<ContactItem>
  <ContactID>987612345</ContactID>
</ContactItem>

Example callback URL post:

POST https://acme.com/QMSResults.jsp HTTP/1.1
Content-Type: text/xml; charset=utf-8
<ContactCollection>
  <ContactItem>
    <Contact>Doe, John</Contact>
    <SCRAStatus>Active</SCRAStatus>
    <SCRAStatusAsOf>8/15/2014</SCRAStatusAsOf>
    <CertificateID>564738291</CertificateID>
  </ContactItem>
</ContactCollection>

Note: QMS active duty searches are not done synchronously because the time lag involved in parsing the DoD’s PDF results makes synchronous calls very inefficient. Thus, searching with a rest hook callback is the preferred method of searching.

Including Your Unique Identifiers

When posting data back to your callback URL, you can cause QMS to regurgitate key information for your own use. For example, assume you are performing an active duty search for a customer from your CMS system, and the customer has a unique ID number. Specify your unique ID number as the “SourceReferenceNumber” data point.

Example request

POST Military.ashx/Search?Callback=https://acme.com/QMSResults.jsp HTTP/1.1
FirstName=John&LastName=Doe&USSSN=123456789&SourceReferenceNumber=MyUniqueID-ABC123

Example synchronous response:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
<ContactItem SourceReferenceNumber="MyUniqueID-ABC123">
  <ContactID>987612345</ContactID>
</ContactItem>

Example callback URL post:

POST https://acme.com/QMSResults.jsp HTTP/1.1
Content-Type: text/xml; charset=utf-8
<ContactCollection SourceReferenceNumber="MyUniqueID-ABC123">
 <ContactItem>
 <Contact>Doe, John</Contact>
 <SCRAStatus>Active</SCRAStatus>
 <SCRAStatusAsOf>8/15/2014</SCRAStatusAsOf>
 <CertificateID>564738291</CertificateID>
 </ContactItem>
</ContactCollection>

This way, you can parse the SourceReferenceNumber submitted to your callback URL, and process the data against your system accordingly.

Retrieving a PDF Certificate

To retrieve the PDF certificate associated with a search:

Example request

GET Military.ashx/Certificate?CertificateID=564738291 HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: XXXXX
{PDF content here}

Note: QMS will retain your PDFs for a year (or more, if you wish). You’re welcome to simply store our CertificateID in your systems, and retrieve the PDF from us on demand as you need.

Data Points (POST parameters)

Parameter Required? Description
FirstName Yes The first name of the person being searched for.
LastName Yes The last name of the person being searched for.
USSSN No* The 9 digit social security number of the person being searched for. Note that ‘fake’ social security numbers such as 999999999 and 111111111 will be rejected and cause an error message to be returned.If you do not submit a USSSN, you must either submit a birth date, or enable our SSN lookup feature (which incurs a cost). If invoking our SSN lookup feature, you must also provide an address.
BirthDate No* If you do not submit a birth date, you must either submit a USSSN, or enable our SSN lookup feature.
Address No Address of the person being searched for. This may include multiple lines.
City No City of the person being searched for.
State No State of the person being searched for.
PostalCode No Five-digit postal code (zip code) of the person being searched for.
SourceReferenceNumber No A unique string regurgitated in QMS responses; this is for consumption by your systems.

Options (GET parameters)

Option Valid Values Description
IncludeCertificate true | false When true, responses will include the PDF certificate as a base64-encoded CDATA node in XML responses.
NamePermutate true | false When true, the QMS name permutations will be applied before searching, so you don’t miss any DoD entries because their name does not quite match your name.
IncludeScreenshot true | false When true, a screenshot of the data submitted to DoD will be included in the results. This provides an audit trail of the data you submitted to DoD.
ToggleMiddleName true | false
ForceHypen true | false
MergeCertificates true | false When true, the PDF certificates for all permutations or aliases searched for a contact are merged into a single result. This is useful when you wish to include a single document in your imaging system for each of your customers searched, instead of a distinct document for each name permutation searched.