DMF Integrated Search API Reference

1. Introduction

   1. Purpose

      This document provides an overview of web services and related processes available for system-to-system interaction with the DMF Integrated Search product. This document is intended for use by technical professionals developing systems which will interface with DMF Integrated Search in an automated capacity.

      This document will be updated as new functionality is added to the DMF Integrated Search product or as service interfaces and authentication procedures are updated.

2. DMF Integrated Search Web service Architecture

   The DMF Integrated Search is designed to provide a simple and intuitive web service interface for NTIS partners to integrate into their systems for the automated exchange of data.

   These web services are built on a REST and JSON architecture, and require a secure connection via HTTPS protocol. Once a connection has been established, the remote system must provide authentication to DMF Integrated Search to ensure the connection is valid and active. Authenticated remote systems will then send requests using available DMF Integrated Search web services and wait for a response. DMF Integrated Search web services will process request as they are received and will return a response over the same connection.

   Connections can be made to the DMF Integrated Search via the following link:

   /api

   1. Authentication

      System-to-system web service authentication credentials are established during registration on the DMF website. Once a profile is setup and approved, credentials are viable for use in authentication to the services and executing DMF Integrated Search web service transactions. Passwords for web service authentication do not expire, but can be reset any time by accessing the account provide or utilizing the forgot password functionality in the DMF website.

      Password complexity is enforced by the DMF website, but are required to be 14-16 characters long with at least one numeric character, one special character , and one uppercase alpha character.

      All requests to the API need to be accompanied by an authorization header with a authentication token:

      Authorization: Bearer 212LJ3k0i2382364HIUEjfeJB98yvH

      Authentication tokens are generated via the token endpoint. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

   2. Errors

      Occasionally, remote connections experience connectivity and/ or authentication errors. This is consistent with connections and services accessed via the internet. The DMF Integrated Search API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a given parameter was incorrect, etc.), and codes in the 5xx range indicate an error with NTIS servers.

      DMF Integrated Search Connectivity and Authentication Errors

      HTTP Status Code	Reason
      401	Incorrect or invalid credentials.
      403	Subscription provided does not qualify for this web service. OR Unable to find available queries for this subscription. . OR Allowed query count exceeded. Please update subscription.
      500	Internal Server Error.

    

3. DMF Integrated Search Web Service

   The DMF web service (DMF Search) provides operations specific to the Death Master File and its records.

   1. Operations

      ID	Protocol	Operation	Description
      1	POST	SearchData	This operation searches the DMF data set.

      1. SearchData

         This operation supports a single DMF_Data object input which is used as search criteria for querying against records in the DMF data set. The service will return all records that are an exact match as it pertains to criteria provided in the supplied fields. If there is no qualified match, the service will return an empty array of DMF_Data object.

         This operation is synchronous.

         This operation is idempotent.

         Parameters

         Name	Description	Data Type
         SearchData	Calls the SearchData operation	DMF_Data

         Request Headers

         Name	Description
         Content-Type:	application/json

         Response

         Name	Description	Data Type
         SearchDataResponse	The operation returns an array (set of zero or more) of DMF record objects.	ArrayOfDMF_Data

    

4. Resources

   For a more low-level details please refer to the API Reference.