For each API call, you must specify whether you want data returned about people, places, households, or entities. Use the document_class parameter to specify this data type. Each API call returns either a person, place, household, or entity document, depending on the document class requested.

The document contains self-identifying attributes such as document type and document id as well as data bundles that include AbiliTec identifiers and other information for the requested person, place, household, or entity.

Batch requests result in a group document that is a collection of response codes and person, place, household, entity, 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 match the order of the requests, so that requests and responses can be paired together.

Person Document

A person document contains information about an individual, including the Person ID for that individual and the individual’s Household ID if the individual is associated with a household in the identity graph.

Place Document

A place document represents an addressable touchpoint such as a physical address, phone, or email. The place document contains information about a touchpoint that is independent of any particular person that might be associated with that touch point, including an Address ID and a Household ID if a household is associated with that address.

Household Document

A household document contains information about a household, including the Household ID and all Consumer IDs for individuals associated with that household.

Entity Document

An entity document identifies documents that are linked together in a particular way. For example, a person at a postal address or a person at a phone number.

Batch Document

A batch document is returned for batch requests. The batch document contains the appropriate document types for each request that was sent in the POST body.

Group Document

A group document is returned when the limit parameter in a request to the Match endpoint is set to a value greater than 1. If there are one or more matches, the group document will contain a number of documents equal to the limit.

The maximum number of documents contained in a group document is 10. Often the number of documents that match the input will be less than the limit, especially when the limit is set closer to 10.

Documents are returned in the order they were matched, with the best match listed first.

The limit parameter does not impact the requirements for a record to become a match; it only allows additional matches to be returned if they exist.

Each document inside the group document is counted as a transaction.

Document Formats

• JSON (default)
• XML
• HTML

Document Content

• 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 are returned only if a persistent document is matched. {~n} for batch response documents only.

General Document Structure

JSON format—Single Response

{
  "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",
      "...": "..."
    },
    "...": "..."
  }
}

JSON format—Single Response

[
  {
    "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",
          "...": "..."
        },
        "...": "..."
      }
    }
  }
]