Maintenance Endpoint

Because new information is constantly coming into the identity graph, you should perform periodic maintenance on the maintained AbiliTec IDs in your system by calling the Maintenance endpoint with the requested document class and maintenance type. You can specify a start date (using the “since” parameter), an end date (using the “until” parameter), or both. If you don’t specify a start or end date, the API returns all maintenance records from the last 18 months.

We recommend that each call to the Maintenance endpoint should specify a start date that corresponds to the date of the previous Maintenance endpoint call up to the current date.

The Maintenance endpoint does not return information on derived AbiliTec IDs. PII that previously resulted in a derived AbiliTec ID should be run through AbiliTec periodically in case new information allows us to link the data to a maintained AbiliTec ID.

The Maintenance endpoint behaves a little differently compared to the other endpoints. When successfully called, the API will respond with a header that provides the parameters to retrieve the next block of data. Typical usage will see the user paginating through all of the maintenance for a given period, simply calling all of the "next" links, until exhausted.

This endpoint is paginated by default at 1000 documents.

URL Format

SINGLE REQUEST ENDPOINT
GET|POST https://us.identity.api.liveramp.com/v1/maintenance/{document_class}/{maintenance_type}?{parameters}

Document Class

Document class is required for Maintenance Endpoint requests. Supported document classes for Maintenance Endpoint are people, places, households, and businesses.

The document class must be specified as part of the URL path. It should be included after the base path but before any endpoint specific components of the path. See the URL Format section above.

Parameter	Type	Description	Valid Values
document_class	string	The document class being requested.	people, places, households, entities

Maintenance Type

Maintenance type is required for Maintenance Endpoint requests. Supported maintenance types are relinks and consolidations. The maintenance type must be specified as part of the URL path. It should be included after the document type. See the URL Format section above for details about replacement.

Parameter	Type	Description	Valid Values
maintenance_type	string	Maintenance Type	relinks, consolidations

Query Parameters

The following table provides details about the optional available parameters for this endpoint.

Parameter	Type	Description	Example Values
since	date	This is a filter on the result set by date. Each maintenance record is associated with a build. The build date is defaulted to the 25th of each month. This filter excludes all maintenance records with an older date.	YYYYMMDD within 18 months
until	date	This is a filter on the result set by date. Each maintenance record is associated with a build. The build date is defaulted to the 25th of each month. This filter excludes all maintenance records with a newer date.	YYYYMMDD within 18 months
entityType	string	This is a filter on the result set by entityType. A comma separated list can be provided. If no value is provided, then it is assumed that all entity types are valid. This is needed to support the legacy operator’s "consumer digital splits". A digital record is equivalent to entity type "nameAndPhone" or "nameAndEmail".	Comma separated list of acceptable entity types: nameAndAddress, nameAndEmail, nameAndPhone Entity types are only valid for consumer level maintenance.

Validation Rules
• since and until parameters must be a valid date within the past 18 months.
• since and until parameters must not be future dates.
• until parameter must be a newer date than the since parameter.
• entityType, if present, must be composed of valid entity types.

Response

All responses return collections of results. These collections contain the document type, change date, and entity type as well as an array of maintenance objects (relinks or consolidations).

Each maintenance record will be a single document object. Additionally, each response will contain within its headers a relative link to the next block of maintenance data. Typical response headers might look something like this:

Maintenance Response Headers

Date: Wed, 11 Apr 2018 16:52:47 GMT
Content-Type: application/json;charset=UTF-8
link: </maintenance/people/relinks?format=json&perPage=1000&id=12&offset=1000>; rel="next"
Content-Language: en-US
Transfer-Encoding: chunked

Person Relink Example

[
  {
    "maintenance": {
      "maintenanceMetadata": {
        "changeDate": "20170115",
        "entityType": "nameAndAddress",
        "documentType": "person"
      },
      "relink": {
        "retiredId": "000000US00XTyTV38YrtdWYNH5At5L3-K7buf3",
        "retiredLink": "0000US020105ZRLQ"
      }
    }
  },
  {
    "maintenance": {
      "maintenanceMetadata": {
        "changeDate": "20170115",
        "entityType": "nameAndAddress",
        "documentType": "person"
      },
      "relink": {
        "retiredId": "000000US00TrwsCgegGvq1feeayuhdq2mif2Ic",
        "retiredLink": "0000US03016FMZ8B"
      }
    }
  }
]

Household Consolidation Example

[
  {
    "maintenance": {
      "maintenanceMetadata": {
        "changeDate": "20170115",
        "documentType": "household"
      },
      "consolidation": {
        "activeId": "000000US00cB0uAQOpj-Jqdgg0lMlGlO3Xy_gd",
        "retiredId": "000000US00O5zwQoFwfHo6mt4_XeapaHdo0w5i",
        "activeLink": "0000US08EF09FFD8",
        "retiredLink": "0000US0ADBC56B7E"
      }
    }
  },
  {
    "maintenance": {
      "maintenanceMetadata": {
        "changeDate": "20170115",
        "documentType": "household"
      },
      "consolidation": {
        "activeId": "000000US00XkzGby4EB9cwMQrazrEqojOjPeFR",
        "retiredId": "000000US0056Gh2mq9seCYmM95MCTejSU6EdFe",
        "activeLink": "0000US09E644A19E",
        "retiredLink": "0000US07FEB44F41"
      }
    }
  }
]

URL Examples

Request for Relinks
GET|POST https://us.identity.api.liveramp.com/v1/maintenance/people/relinks

The above request will return, in the body of the response, the first block of maintenance with document type person, and maintenance type relink. Additionally, a link header will be returned alongside other response headers, providing applications the link to retrieve the next block of maintenance data.

Request for Consolidations
GET|POST https://us.identity.api.liveramp.com/v1/maintenance/places/consolidations