Documents

Each request resolves to either a person, place, household, residency, business, or entity document based on the document id or document_class parameter requested. For each request, you must determine whether you want data returned about people, places, households, residencies, businesses, or entities. You also have the option of specifying which bundles are included in the response data in your API call. The document (person, place, household, residency, business, or entity) you retrieve will contain only the bundles you request. If you do not request specific bundles, all bundles to which you have access will be returned in the document.

When developing to the API, it is important to understand that even if a document class (e.g., person) may contain a particular bundle, the particular bundle may or may not be present in a given document. For example, the person document for “John Smith” may contain a phoneContact bundle because there is a phone number associated with “John,” but the person document associated with “Mary Robinson” may not have a phoneContact bundle because “Mary” has chosen to add her phone number to the national “Do Not Call” list. Developers should code their applications to deal with either the presence or absence of each requested bundle on any given request.

The API returns a document in the requested format. The document contains self-identifying attributes (document type and document id) as well as data bundles that include attributes and linkage for the requested person, place, residency, business, or household.

Batch requests result in a single document that is a collection of response codes and person, place, household, entity, residency, business, and/or error documents for each request. The types of documents returned in the collection are based on the document id or document_class parameter requested on the individual requests. The order of documents in the collection will match the order of the requests, so that requests and responses can be paired together easily.

• json (default)
• xml
• html

• document type – identifies the classification of the document (person or place).
• document id** – uniquely identifies the persistent document.
• metadata – document metadata. See the document structure and example documents below.
• data bundles[1..*] – includes attributes of the person or place and linkage to other people or places.
• code - response code related to a specific request
• document - container for document content in a batch response

In response to a match request, the document id and metadata will only be returned if a persistent document is matched. {~n} for batch response documents only

{
  "document_type": {
    "id": "id",
    "metadata": {
      "createDate": "YYYY-MM-DDTHH:MM:SS-0600",
      "updateDate": "YYYY-MM-DDTHH:MM:SS-0600",
      "version": "version"
    },
    "data_bundle": {
      "attribute_name": "attribute_value",
      "...": "..."
    },
    "...": "..."
  }
}

[
  {
    "code": "code_value",
    "document": {
      "document_type": {
        "id": "id",
        "metadata": {
          "createDate": "YYYY-MM-DDTHH:MM:SS-0600",
          "updateDate": "YYYY-MM-DDTHH:MM:SS-0600",
          "version": "version"
        },
        "data_bundle": {
          "attribute_name": "attribute_value",
          "...": "..."
        },
        "...": "..."
      }
    }
  },
  "...",
  {
    "code": "code_value",
    "document": {
      "error": {
        "message": "message_text",
        "code": "application_error_code",
        "requestId": "request_ID_stamp"
      }
    }
  },
  {
    "code": "code_value",
    "document": {
      "document_type": {
        "id": "id",
        "metadata": {
          "createDate": "YYYY-MM-DDTHH:MM:SS-0600",
          "updateDate": "YYYY-MM-DDTHH:MM:SS-0600",
          "version": "version"
        },
        "data_bundle": {
          "attribute_name": "attribute_value",
          "...": "..."
        },
        "...": "..."
      }
    }
  }
]