❗ Important

We have enhanced our API offerings! The new set of APIs enables you to automate and accomplish a number of tasks without you requiring to login in inSync Management Console every time. For a complete list of APIs and how to use it, see Druva Developer Portal.

Overview

Using the Legal Hold API (Application Programming Interface), you can run the Legal Hold tasks through an automated workflow. If you use the Legal Hold APIs, you are not required to log on to the inSync Management Console and perform the tasks manually, such as, put a user on Legal Hold.

For example, a legal counsel or litigation support administrator in a large enterprise can use a script to call the Legal Hold APIs and automate the configuration tasks for Legal Hold.

📝 Note
Only the inSync Cloud administrator can use the Legal Hold APIs for automating the configuration tasks.

What operations are supported by Legal Hold APIs?

You can use the Legal Hold APIs to perform the following tasks:

List all the Legal Hold policies for a user
Get details of a Legal Hold policy
Create a Legal Hold policy
Delete an existing Legal Hold policy
Add users to a Legal Hold policy
List users of a Legal Hold policy
Remove users from a Legal Hold policy

To use the Legal Hold APIs, you must obtain the authentication information from inSync Management Console. You can then create a script to request for Legal Hold APIs and automate the Legal Hold tasks.

What versions are available for Legal Hold APIs?

Legal Hold APIs have 2 versions. The following table lists the API Request for the GET API (API to get details of a Legal Hold policy) to explain the difference between the 2 versions.

Version	Request	Description
v1	GET /api/legalholds/ v1 /<legalhold id>	Contains v1 in the API request.
v2	GET /api/legalholds/ v2 /<legalhold id>	Contains v2 in the API request. With v2, ##################{{insync}}has added support for the new Data within a Date Range data access type. This allows you to view created files, modified files, and deleted files within a particular date range.
v3	GET / insync/legalholds/v3 /<{policies}/{users}>	The API host URL has changed. The authentication method has changed. Legal Hold API v3 has a new API which lists all the Legal Hold policies associated with a user. For detailed documentation of Legal Hold API v3, see Druva Developer Portal.

Prerequisite

Before you start using the Legal Hold APIs, ensure a valid Governance license is available at your inSync Cloud environment.

How to obtain the authentication information?

inSync uses HTTP Basic authentication for API requests. inSync Cloud administrator can create the authentication information from the inSync Management Console.

The authentication information consists of the following components:

Username: Email ID of the inSync Cloud administrator who creates the authentication token.
Password: Authentication token that is generated.

inSync stores the authentication information in the database, that is encrypted with the ekey of your organization. Whenever you request to access the API, you must specify the username and the password.

Procedure

To obtain the authentication information:

Log on to the inSync Management Console as an inSync Cloud administrator.
On the inSync Management Console menu bar, click the Settings icon. The Settings page appears.
Click the inSync APIs tab. The Access token for inSync APIs page appears.
Click Copy Token. The token is copied to your clipboard.
The Copy Token button is available only when the authentication token is valid.
If the token has expired, then click Create New Token and run the following steps:
1. In the Expire on field, specify the expiry date of the authentication token.
2. Click Done.
Copy the token and retain it for requesting access to the API.

📝 Note
By default, the token is valid for 30 days. The token's expiry date can be anywhere between 1 day to 365 days. You can create a new token even if the existing token is valid, if you feel that the token is compromised.

List of Legal Hold APIs

Click the specific task to view the information about the Legal Hold API.

APIs available in v2

API to list all the Legal Hold policies

Description: Lists all the Legal Hold policies that are available in your ##################{{insync}}Cloud environment.
Request: GET /api/legalholds/v2
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Response(JSON):
- If type is Data within a Date Range:
  HTTP 200: {‘legal_hold_list’: [{'policy_id': ,'name': ,'type':, ‘culling_type’:, ‘start_date’:, ‘end_date’:}, ...]}
- In other cases:
  HTTP 200: {'legal_hold_list': [{'policy_id': ,'name': ,'type': }, ...]}
- HTTP4XX/5XX: { 'errno': , 'desc': }}

API to get details of a Legal Hold policy

Description: Retrieve the details of a Legal Hold policy in your ##################{{insync}}Cloud environment.
Request: GET /api/legalholds/v2/<legalholdid>
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Response(JSON):
- If Data Access type is Data within a Date Range:
  HTTP 200: {'policy_id': ,'name': ,'type': , ‘no_of_custodians’:, ‘culling_type’:, ‘start_date’:, ‘end_date’:, ‘webdav_url’:}
  where, the ' wedav_url' key contains a list of encoded URLs (special characters andunicodecharacters are encoded and then converted to their ASCII values) that are used to access data for that Legal Hold policy.
- In other cases:
  HTTP 200: {'policy_id': ,'name': ,'type': , ‘no_of_custodians’:, ‘webdav_url’:}
- HTTP4XX/5XX: { 'errno': , 'desc': }}

API to create Legal Hold policy

Description: Create a Legal Hold policy in your ##################{{insync}}Cloud environment.
Request: POST /api/legalholds/v2
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Request_Body(JSON):
- where type is either ' All Collected Data ', ' Last Collected Data ':
  {'name' : , 'type': }
- where type is Data within a Date Range and 'culling_type'is ' Include All Files 'or ' Include Only Deleted Files ':
  {‘name’:, ‘type’:, culling_type’:, ‘start_date’:, ‘end_date’: }
  
  📝 Note
  For data access type All Collected Data and Last Collected Data admin cannot specify 'culling_type', 'start_date' and 'end_date' parameters.
Response(JSON) :
- HTTP4XX/5XX: { 'errno': , 'desc':}
- HTTP 200 : {'policy_id': }

API to delete Legal Hold policy

Description: Delete the Legal Hold policy from your ##################{{insync}}Cloud environment.
Request:DELETE /api/legalholds/v2/<legalholdid>
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Response(JSON):
- HTTP 200: {}
- HTTP4XX/5XX: { 'errno': , 'desc': }

API to add users to Legal Hold policy

Description: Adds users to a Legal Hold policy in your ##################{{insync}}Cloud environment
Request:POST /api/legalholds/v2/<legalholdid>/users
Request_Headers : Authorization = <LOGIN CREDENTIALS>
Request_Body: {‘action’:’add’, ‘custodians’: [{'email_id':}...]}
Response(JSON):
- HTTP 200 :{'not_insync_users':[{'email_id':}...], 'already_on_legalhold':[{'email_id':}...]}
- HTTP4XX/5XX: { 'errno': , 'desc': }

API to list the users on Legal Hold

Description: Retrieve the list of users who are on Legal Hold in your ##################{{insync}}Cloud environment.
Request: GET /api/legalholds/v2/<legalholdid>/users
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Response(JSON):
- HTTP4XX/5XX: { 'errno': , 'desc': }
- HTTP 200 : {'custodians' : [{'email_id':, ‘webdav_url’: }, ..]}
  where the webdav_url key contains the URL used to access the data of a user for that Legal Hold policy.

API to remove users from Legal Hold

Description: Removes users from Legal Hold in your ##################{{insync}}Cloud environment.
Request:POST /api/legalholds/v2/<legalholdid>/users
Request_Headers : Authorization = <LOGIN CREDENTIALS>
Request_Body : {‘action’:’delete’, ‘custodians’: [{'email_id':}...]}
Response(JSON):
- HTTP 200:{'not_insync_users':[{'email_id':}...], 'not_on_legalhold':[{'email_id':}...]}
- HTTP4XX/5XX: { 'errno': , 'desc': }

APIs available in v1

API to list all the Legal Hold policies

Description: Lists all the Legal Hold policies that are available in your ##################{{insync}}Cloud environment.
Request:GET /api/legalholds/v1
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Response(JSON):
- HTTP 200: {'legal_hold_list': [{'policy_id': ,'name': ,'type': }, ...]}
- HTTP4XX/5XX: { 'errno': , 'desc': }}

API to get details of a Legal Hold policy

Description: Retrieve the details of a Legal Hold policy in your ##################{{insync}}Cloud environment.
Request:GET /api/legalholds/v1/<legalholdid>
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Response(JSON):
- HTTP 200: {'policy_id': ,'name': ,'type': , 'no_of_custodians':}
- HTTP4XX/5XX: { 'errno': , 'desc': }}

API to create Legal Hold policy

Description: Create a Legal Hold policy in your ##################{{insync}}Cloud environment.
Request:POST /api/legalholds/v1
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Request_Body(JSON): {'name' : , 'type': }

Type can be either 'All Collected Data' or 'Last Collected Data'
Response(JSON) :
- HTTP4XX/5XX: { 'errno': , 'desc':}
- HTTP 200 : {'policy_id': }

API to delete Legal Hold policy

Description: Delete the Legal Hold policy from your ##################{{insync}}Cloud environment.
Request:DELETE /api/legalholds/v1/<legalholdid>
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Response(JSON):
- HTTP 200: {}
- HTTP4XX/5XX: { 'errno': , 'desc': }

API to add users to Legal Hold policy

Description: Adds users to a Legal Hold policy in your ##################{{insync}}Cloud environment
Request:POST /api/legalholds/v1/<legalholdid>/users
Request_Headers : Authorization = <LOGIN CREDENTIALS>
Request_Body : {‘action’:’add’, ‘custodians’: [{'email_id':}...]}
Response(JSON) :
- HTTP 200 :{'not_insync_users':[{'email_id':}...], 'already_on_legalhold':[{'email_id':}...]}
- HTTP4XX/5XX: { 'errno': , 'desc': }

API to list the users on Legal Hold

Description: Retrieve the list of users who are on Legal Hold in your ##################{{insync}}Cloud environment.
Request:GET /api/legalholds/v1/<legalholdid>/user
Request_Headers: Authorization = <LOGIN CREDENTIALS>
Response(JSON):
- HTTP4XX/5XX: { 'errno': , 'desc': }
- HTTP 200 : {'custodians' : [{'email_id': }, ..]}

API to remove users from Legal Hold

Description: Removes users from Legal Hold in your ##################{{insync}}Cloud environment.
Request:POST /api/legalholds/v1/<legalholdid>/users
Request_Headers : Authorization = <LOGIN CREDENTIALS>
Request_Body : {'action':'delete', 'custodians': [{'email_id':}...]}
Response(JSON) :
- HTTP 200:{'not_insync_users':[{'email_id':}...], 'not_on_legalhold':[{'email_id':}...]}
- HTTP4XX/5XX: { 'errno': , 'desc': }

API response codes

This section lists the API response codes generated based on the request to access Legal Hold APIs.

inSync processes the API request and displays the following response codes:

Response Codes	Description
HTTP 200	Request is successful.
HTTP 400	Request syntax is incorrect. For example, Request Headers are not present.
HTTP 401	Authentication was not successful. This response code is generated in one of the following scenarios: The access request does not have the required parameters. The access request has invalid parameters, like incorrect Username and/or Password.
HTTP 403	License is not valid. You do not have a valid license to access the API. Contact Support to get the license.
HTTP 404	Requested Legal Hold policy was not found. For example, incorrect Legal Hold policy ID is mentioned.
HTTP 409	This error can be seen in any of the following scenarios: Invalid characters in the Legal Hold policy name while creating a policy. For example, characters such as forward slash ( /), colon ( :), asterisk ( ), question mark ( ?), less-than ( <), greater than ( >), vertical bar ( \|), double backslash ( \\), double quotation mark ( " ). A `- /:?<>\|\\" are not allowed in policy name.` message appears. You requested to create a Legal Hold policy and a policy with a similar name already exists. An `Another Legal Hold policy with the same name already exists. Please specify a unique name for the new Legal Hold policy.` message appears.
HTTP 429	Too many API requests received by inSync Server in a given amount of time. Try requesting the API after some time.
HTTP 500	Some other internal server error in processing the Legal Hold API request. An `Internal Error` message appears.

About legal hold

Create roles for a Legal Administrator

Access legal hold

Access legal hold data using WebDAV

Governance and Legal Hold for OneDrive data