Legal Hold APIs

Legal Hold API includes APIs for authorization with Graph API and a public endpoint for getting active custodian details. To view the Legal Hold API, click Legal Hold REST API Reference

Matter or project management

The following APIs can be used for any matter or project management function, including integrating with matter management systems.

ActiveCustodianSummary

The ActiveCustodianSummary endpoint provides a list of all custodians who are actively on-hold. Released custodians are not included. 1000 records maximum can be returned at a time, but you can adjust the StartingIndex parameter to pull more back if you get 1000. If a user is on hold for multiple projects, they still only have a single entry in the returned JSON.

API returns JSON including the following information:

  • Project ID
  • Full Name
  • First Name
  • Last Name
  • Email
  • Employee Number (empty string if not populated)
  • UniqueID (empty string if not populated)
  • Error Message (only returns on a bad request)

This endpoint can be used for getting JSON-formatted data and parsing it for your own internal systems or reporting. While reporting functionality exists within Relativity to get the same or similar data, this endpoint makes it easy to get the data you need quickly and easily with your existing system.

EmployeeNumber and UniqueID are fields that are used differently by each organization. They are returned as strings to accommodate each tenant's needs. For some tenants, these are empty strings as the fields are not used by the organization.

Copy 
/Relativity.Rest/API/kCura.LegalHold.Services.ILegalHoldModule/Custodian-Request-Manager/ActiveCustodianSummary?workspaceId={workspaceID}&startingIndex={startingIndex}&length={length}
 
            Example: /Relativity.Rest/API/kCura.LegalHold.Services.ILegalHoldModule/Custodian-Request-Manager/ActiveCustodianSummary?workspaceId=3961297&startingIndex=0&length=500

JSON request (If the body is empty, indicate that here. Provide information about any fields in the request that need special handling or need additional explanation.)

Copy
JSON request
Request body will be empty
                Parameters:
                WorkspaceID = The Artifact ID of the workspace you are querying
                StartingIndex = The starting index for your query. 1 and 0 are both treated as 0. Use this for paging your request.
            Lentgh = Maximum value of 1000, dictates how many records are returned

JSON response (If the body is empty, indicate what is returned, such as ArtifactID or status code. Provide information about any fields in the request that need additional explanation.)

Copy
JSON response
[
                {
                "ProjectID": 1042311,
                "FullName": "Doe, John",
                "FirstName": "John",
                "LastName": "Doe",
                "EmailAddress": "johndoe@example.com",
                "EmployeeNumber": "111",
                "UniqueID": "johndoe111"
                },
                {
                "ProjectID": 1042311,
                "FullName": "Johnson, Bob",
                "FirstName": "Bob",
                "LastName": "Johnson",
                "EmailAddress": "bobjohnson@example.com",
                "EmployeeNumber": "",
                "UniqueID": ""
                },
                {
                "ProjectID": 1042042,
                "FullName": "Howard, Catherine",
                "FirstName": "Catherine",
                "LastName": "Howard",
                "EmailAddress": CathyHoward@example.com",
                "EmployeeNumber": "333",
                "UniqueID": "cathy333"
                },
                {
                "ProjectID": 1042311,
                "FullName": "Howard, Catherine",
                "FirstName": "Catherine",
                "LastName": "Howard",
                "EmailAddress": CathyHoward@example.com",
                "EmployeeNumber": "333",
                "UniqueID": "cathy333"
                }
            ]

Creating a Legal Hold project

The following REST calls create a Legal Hold project with the following fields:

  • Full Name
  • Email
  • Use as Template (defaulted to No)
  • Project Status (must specify ArtifactID of the Active choice)
Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{Workspace_ID}/object/create
Copy
JSON Request
{
                "Request":{
        
                "ObjectType":{
                "Name": "Project"
                },
 
                "FieldValues":[
                {
                "Field":{
                "Name": "Name"
                },
                "Value":"Postman Test Project"
                },
                {
                "Field":{
                "Name": "Owner Email"
                },
                "Value":"myemail@relativity.com"
                },
                {
                "Field":{
                "Name": "Use as Template"       
                },
                "Value":false
                },
                {
                "Field":{
                "Name": "Project Status"        
                },
                "Value":{
                "ArtifactID":1067257 
                }
                }       
                ]
                }
            }

Querying a Legal Hold project

The following REST call returns the names of all Legal Hold projects in the workspace.

Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{Workspace_ID}/object/query
Copy
JSON REQUEST
{
   "Request":{
      "ObjectType":{
         "Name": "Project"
      },
      "fields":[
         {"Name": "Name"}
      ],
      "sorts":[
      ]
   },
   "start":1,
   "length":100
}

Querying for Custodians on a Legal Hold project

The following REST call returns the names of all Custodians and their role on a Legal Hold project.

Replace the ID in "condition" with the Project ArtifactID which you are trying to query from.

Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{Workspace_ID}/object/query
Copy
JSON REQUEST
{
   "Request":{
      "ObjectType":{
         "Name": "Custodian Role"
      },
      "fields":[
         {"Name": "Custodian"},
         {"Name": "Role"}
      ],
      "condition":" 'Project' == <project_artifact_id>", 
      "sorts":[
      ]
   },
   "start":1,
   "length":100
}

Creating a communication

The following REST call adds a communication to a Legal Hold project with the following fields:

  • Name
  • Acknowledgment Required
  • Communication Type (specify ArtifactID of the Communication Type choice)
  • DisplayInPortal
  • Email Body
  • Email Subject
  • Enable Automatic Escalation - If set to true, you must also specify:
    • Allotted Escalations
    • Escalation Interval
    • Escalation Recipient
    • Escalation Subject
    • Escalation Detail
  • Enable Reminders - If set to true, you must also specify:
    • Allotted Reminders
    • Reminder Interval
    • Reminder Subject
    • Reminder Body
  • Project (specify ArtifactID of the project to add the communication to)
  • Use as Template (defaulted to No)

Optional BCC fields:

  • BCC People
  • BCC Subject
  • BCC Body
Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{Workspace_ID}/object/create
Copy
JSON REQUEST
{
   "Request":{
        
      "ObjectType":{
          "Name": "Communication"
        },
 
"FieldValues":[
         {
            "Field":{
                "Name": "Name"
            },
            "Value":"Postman Test Communication 2"
         },
         {
            "Field":{
                "Name": "Acknowledgement Required"
            },
            "Value":false
         },
         {
            "Field":{
                "Name": "Communication Type"
            },
            "Value":{"ArtifactID":<communication_type_choice_id>}
         },
         {
            "Field":{
                "Name": "DisplayInPortal"
            },
            "Value":true
         },    
         {
            "Field":{
                "Name": "Email Body"
            },
            "Value":"<!DOCTYPE html><html><title>HTML Tutorial</title><body><h1>This is a heading</h1><p>This is a paragraph.</p></body></html>"
         }, 
         {
            "Field":{
                "Name": "Email Subject"
            },
            "Value":"Test Email"
         },
         {
            "Field":{
                "Name": "Enable Automatic Escalation"
            },
            "Value":false
         },
         {
            "Field":{
                "Name": "Enable Reminders"
            },
            "Value":false
         }, 
         {
            "Field":{
                "Name": "Project"
            },
            "Value":{"ArtifactID":<project_artifact_id>}
         },
         {
            "Field":{
                "Name": "Use as Template"
            },
            "Value":false
         }
    ]
   }
}

Preservation in Place (PIP Application)

If you are using the Preservation application you can utilize the following APIs for interacting with the application. For more information on the Preservation application, see Preservation on the RelativityOne Documentation site.

Preserving data

The following REST call creates a preservation object and initiate preservation holds for the specified entities and data sources/services.

Provide one of the following:

  • LegalHoldProjectID - use if a previous preservation has not been run.
  • PreservationID - ArtifactID of the preservation.
  • PreservationName - name of the preservation (should be the same as the project name).

In the following example, an entity for Microsoft Mailbox and OneDrive along with an entity for Google Gmail, Chat, and Drive are being preserved. If entities are provided without the specified data service IDs, then it preserves those entities for all available custodial data services.

Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Preservations/v1/Preservations/workspace/{workspaceId}/preservation/PreserveEntities/
Copy
JSON REQUEST
{
    "preservationRequest": {
        "LegalHoldProjectId": "<integer>",
        "PreservationId": "<integer>",
        "PreservationName": "<string>",
        "SourceIds": [
            "<o365SourceId>",
            "<gVaultSourceId>"
        ],
        "EntitiesToPreserve": {
            
            "<entityID>": [ 
                "<MailboxServiceID>", "<OneDriveServiceID>"
            ],
            "<entityID>": [ 
                "<GmailServiceID>", "<GChatServiceID>", "<GDriveServiceID>"
            ],
        },
        "NonCustodialDataIds": [
        ],
        "StartPreservationJobs": "true"
    }
}

Releasing data

The following REST call releases the specified custodians from specified data sources/services.

Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Preservations/v1/Preservations/workspace/{workspaceId}/preservation/{preservationId}/ReleaseCustodians/
Copy
JSON REQUEST
{
    "releaseRequest": {
        "SourceIds": [
            "<o365SourceId>",
            "<gVaultSourceId>"
        ],
        "EntitiesToRelease": {
            
            "<entityID>": [
                "<MailboxServiceID>", "<OneDriveServiceID>"
            ],
            "<entityID>": [
                "<GmailServiceID>", "<GChatServiceID>", "<GDriveServiceID>"
            ],
        },
        "NonCustodialDataIds": [
        ],
        "StartPreservationJobs": "true"
    }
}

Closing preservation

The following REST call closes a preservation and all holds associated with it.

Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Preservations/v1/Preservations/workspace/{workspaceId}/preservation/{preservationId}/ClosePreservation

HR Integrations

You can use the following APIs to build integration for importing custodians. For more information on ways to import Custodians, see Importing entities via Integration Points on the RelativityOne Documentation site.

Creating an entity

The following REST call creates an entity with the following fields:

  • First Name
  • Last Name
  • Email
Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{Workspace_ID}/object/create
Copy
JSON REQUEST
{
   "Request":{
        
    "ObjectType":{
          "Name": "Entity"
        },
 
    "FieldValues":[
            {
            "Field":{
                "Name": "Full Name"
            },
            "Value": "<last_name_,_first_name>"
            },
            {
            "Field":{
                "Name": "First Name"
            },
            "Value": "<first_name>"
            },
            {
            "Field":{
                "Name": "Last Name"
            },
            "Value": "<last_name>"
            },
           {
            "Field":{
                "Name": "Email"
            },
            "Value": "<email>"
            }     
    ]
   }
}

Updating entity employee status

The following REST call updates the employee status of an entity.

Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{Workspace_ID}/object/update
Copy
JSON REQUEST
{
   "request":{
      "Object":{
         "artifactId": <entity_artifact_id>
      },
      "FieldValues":[
         {
            "Field":{
               "Name": "Employee Status"
            },
            "Value": "<employee_status>"
         }
      ]
   }
}

Task Management

You can use the following APIs for creating and updating Legal Hold Tasks. For information on creating and tracking tasks, see Task tracking on the RelativityOne Documentation site.

Creating a Legal Hold task

The following REST call creates a Legal Hold task with the following fields:

  • Name
  • Type
  • Status
  • Project
Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{Workspace_ID}/object/create
Copy
JSON REQUEST
{
   "Request":{
        
    "ObjectType":{
          "Name": "Legal Hold Task"
        },
 
    "FieldValues":[
            {
            "Field":{
                "Name": "Name"
            },
            "Value": "<task_name>"
            },
            {
            "Field":{
                "Name": "Task Type"
            },
            "Value": {"ArtifactID": <task_type_choice_id>} 
            },
            {
            "Field":{
                "Name": "Status"
            },
            "Value": {"ArtifactID": <status_choice_id>} 
            },
           {
            "Field":{
                "Name": "Project"
            },
            "Value":{"ArtifactID": <project_artifact_id>}
            }     
    ]
   }
}

Updating Legal Hold task status

The following REST call updates the status field of a Legal Hold task.

Copy
POST call to the following URL
https://{Instance_URL}/Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{Workspace_ID}/object/update
Copy
JSON REQUEST
{
   "request":{
      "Object":{
         "artifactId": <task_artifact_id> 
      },
      "FieldValues":[
         {
            "Field":{
               "Name": "Status"
            },
            "Value":{
               "ArtifactID": <status_choice_id> 
            }
         }
      ]
   }
}