Delete entity history

Learn more about how to use the Delete Entity History API to bulk delete history and activity log entries for a list of entities.

Use the Delete Entity History to bulk delete history and activity log entries for a list of entities. The request body accepts an array of entity URIs.

For each entity, all history and activity log entries are removed except for the first and last entries. When the retainAuditTrail option is omitted, all information except the entity URI is also removed from those boundary entries. To preserve the information in those entries, pass options=retainAuditTrail as a query parameter.

The deletion applies to all losers associated with the submitted entity. If an entity is itself a loser, the API resolves it to its winner and collects all associated losers to delete their history as well.

Important: All activities must be indexed for the entity before running this request. Unindexed activity log entries are not removed correctly.

HTTP method and endpoint

Use the following HTTP method and endpoint path to submit the request for deleting history and activity log entries for a list of entities.

POST {TenantURL}/entities/_deleteHistory

The following table describes the endpoint path parameter.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL of the tenant. Example: `https://test.reltio.com/reltio/api/SampleTenant`.

Query parameters

The following table describes the supported query parameters.


Parameter	Type	Required	Description	Accepted values / Default
`options`	String	No	Controls whether audit trail entries are retained after deletion.	`retainAuditTrail` preserves the information in the first and last history and activity log entries. When omitted, all information except the entity URI is removed from those entries.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	Bearer `<access_token>`	Yes
`Content-Type`	`application/json`	Yes

Request body

The request body accepts a JSON array of entity URIs whose history and activity log entries will be deleted. The maximum number of entity URIs per request is 100.


Parameter	Type	Required	Description	Accepted values / Default
Entity URI array	Array of strings	Yes	JSON array of entity URI strings to delete history and activity log entries for. Each string in the array is an entity URI, for example, `entities/11`.	Maximum: 100 URIs per request.

Example request

Use the following example to see how a complete request is structured with headers and a JSON body.

POST {TenantURL}/entities/_deleteHistory
[
  "entities/11",
  "entities/22"
]

To preserve the content of the first and last audit entries, add the retainAuditTrail option to the endpoint.

POST {TenantURL}/entities/_deleteHistory?options=retainAuditTrail
[
  "entities/11",
  "entities/22"
]

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`<entityURI>`	Object	Top-level key corresponding to each entity URI submitted in the request body. Contains the deletion results for that entity.
`<entityURI>.activity`	Object	Result of the activity log deletion for the entity.
`<entityURI>.activity.status`	String	Outcome of the activity log deletion. Accepted values: `success`, `failed`.
`<entityURI>.activity.error`	String	Error message returned when the activity log deletion fails. Present only when `status` is `failed`.
`<entityURI>.history`	Object	Result of the history deletion for the entity.
`<entityURI>.history.status`	String	Outcome of the history deletion. Accepted values: `success`, `failed`.

Example response

The following example shows a response with success and failed statuses for two submitted entity URIs.

{
  "entities/11": {
    "activity": {
      "status": "success"
    },
    "history": {
      "status": "success"
    }
  },
  "entities/22": {
    "activity": {
      "status": "failed",
      "error": "Some activity error"
    },
    "history": {
      "status": "success"
    }
  }
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`400 Bad Request`	The request contains invalid or missing parameters, or the entity URI array exceeds 100 entries.	Review the request payload, ensure the URI list does not exceed 100 entries, and resend the request.
`401 Unauthorized`	The access token is missing, expired, or invalid.	Obtain a valid access token and resubmit the request. For details, see Authentication API.
`403 Forbidden`	The authenticated user does not have the `DELETE` privilege on the `MDM.Data.Entities.History` resource.	Contact your tenant administrator to verify that the required permissions are assigned to your role.

Unify and manage your data