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