Skip to main content

How can we help you?

Druva Documentation

Use legal hold APIs to automate the configuration tasks

 

License editions: To understand the applicable license editions, see Plans & Pricing.

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:
  1. Log on to the inSync Management Console as an inSync Cloud administrator.
  2. On the inSync Management Console menu bar, click wheel.png > Settings. The Settings page appears.
  3. Click the inSync APIs tab. The Access token for inSync APIs page appears.
  4. Click Copy Token. The token is copied to your clipboard.
    The Copy Token button is available only when the authentication token is valid. 
  5. 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.
  6. 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': }, ...]}
    • HTTP 4XX/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/<legalhold id>
  • 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 and unicode characters 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’:}
    • HTTP 4XX/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’: }
      For data access type All Collected Data and Last Collected Data admin cannot specify 'culling_type', 'start_date' and 'end_date' parameters.
  • Response(JSON) :
    • HTTP 4XX/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/<legalhold id>
  • Request_Headers: Authorization = <LOGIN CREDENTIALS>
  • Response(JSON):
    • HTTP 200: {}
    • HTTP 4XX/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/<legalhold id>/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':}...]}
    • HTTP 4XX/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/<legalhold id>/users
  • Request_Headers: Authorization = <LOGIN CREDENTIALS>
  • Response(JSON):
    • HTTP 4XX/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/<legalhold id>/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':}...]}
    • HTTP 4XX/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': }, ...]}
    • HTTP 4XX/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/<legalhold id>
  • Request_Headers: Authorization = <LOGIN CREDENTIALS>
  • Response(JSON):
    • HTTP 200: {'policy_id': ,'name': ,'type': , 'no_of_custodians':}
    • HTTP 4XX/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) :
    • HTTP 4XX/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/<legalhold id>
  • Request_Headers: Authorization = <LOGIN CREDENTIALS>
  • Response(JSON):
    • HTTP 200: {}
    • HTTP 4XX/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/<legalhold id>/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':}...]}
    • HTTP 4XX/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/<legalhold id>/user
  • Request_Headers: Authorization = <LOGIN CREDENTIALS>
  • Response(JSON):
    • HTTP 4XX/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/<legalhold id>/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':}...]}
    • HTTP 4XX/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 Druva 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.