Legal Holds API Method Reference

If you're sending a POST request to the Legal Holds API, you need to send the input below as application/x-www-form-urlencoded data.

Methods

Policies

Use these methods to define and manage Legal Hold policies.

Custodians

Use these methods to add or remove custodians to or from a Legal Hold policy.


admin.legalHold.policies.activate

This method activates a previously released policy. Activating a policy will hold data visible to custodians specified by the policy.

Method URL: https://slack.com/api/admin.legalHold.policies.activate
Required scope: admin.legalHolds:write
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
policy_id Hxxxxxxxxx Required Policy ID to activate.

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "policy_id": "H01RR4604RZ"
}

Example Response

{
  "ok": true,
  "policy": {
    "id": "H01RR4604RZ",
    "team_id": "E81A4BN3H",
    "creator_id": "WKUNKUXSL",
    "name": "First Policy",
    "description": "...",
    "restrictions": [
      "NO_RESTRICTION"
    ],
    "status": "ACTIVE",
    "date_created": 1616084896,
    "date_updated": 1616084896,
    "date_released": 0,
    "date_policy_start": 0,
    "date_policy_end": 0
  }
}

Return to method list

admin.legalHold.policies.create

This method creates a new Legal Hold policy. By default all policies are created as ACTIVE (enforced) policies.

Method URL: https://slack.com/api/admin.legalHold.policies.create
Required scope: admin.legalHolds:write
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
name Policy name Required A textual name for the policy. This must be a unique name.
description Content under review for case xxxx Optional A long form textual description of the policy.
policy_start_date 1606809600 Optional Unix timestamp of when a policy should start. Omit to hold all historical data. This value cannot be changed once a policy is created.
policy_end_date 1609401600 Optional Unix timestamp of when a policy should end. Omit to hold data until policy release. This value cannot be changed once a policy is created.
restrictions ["ONLY_DMS"] Optional You can either pass ONLY_DMS or omit this argument to set no restrictions on the policy. See example request below for the no restrictions use case. More details in the Restrictions section reference.

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "name": "Second Policy",
  "description": "A policy covering custodians in group A"
}

Example Response

{
  "ok": true,
  "policy": {
    "id": "H01S3583Z4M",
    "team_id": "E81A4BN3H",
    "creator_id": "WKUNKUXSL",
    "name": "Second Policy",
    "description": "A policy covering a custodians in group A",
    "restrictions": [
        "NO_RESTRICTION"
    ],
    "status": "ACTIVE",
    "date_created": 1616516022,
    "date_updated": 1616516022,
    "date_released": 0,
    "date_policy_start": 0,
    "date_policy_end": 0
  }
}

Return to method list

admin.legalHold.policies.info

This method returns the complete details for an existing Legal Hold policy.

Method URL: https://slack.com/api/admin.legalHold.policies.info
Required scope: admin.legalHolds:read
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
policy_id Hxxxxxxxxx Required Policy ID to activate.

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "policy_id": "H01RR4604RZ"
}

Example Response

{
  "ok": true,
  "policy": {
    "id": "H01RR4604RZ",
    "team_id": "E81A4BN3H",
    "creator_id": "WKUNKUXSL",
    "name": "First Policy",
    "description": "",
    "restrictions": [
        "NO_RESTRICTION"
    ],
    "status": "ACTIVE",
    "date_created": 1616084896,
    "date_updated": 1616084896,
    "date_released": 0,
    "date_policy_start": 0,
    "date_policy_end": 0
  }
}

Return to method list

admin.legalHold.policies.list

This method returns a paginated list of Legal Hold policies.

Method URL: https://slack.com/api/admin.legalHold.policies.list
Required scope: admin.legalHolds:read
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
cursor Hxxxxxxxxx Optional Specify to obtain the next page of results from a previous response next_cursor value.
limit 10 Optional Number of policies to return per page. (Max: 1000, Default: 1000)
status RELEASED Optional Limit responses to only include policies of a given status. (E.g.: ACTIVE or RELEASED)

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx"
}

Example Response

{
  "ok": true,
  "policies": [
    {
      "id": "H01S3583Z4M",
      "team_id": "E81A4BN3H",
      "creator_id": "WKUNKUXSL",
      "name": "Second Policy",
      "description": "A policy covering a custodians in group A",
      "restrictions": [
        "NO_RESTRICTION"
      ],
      "status": "ACTIVE",
      "date_created": 1616516022,
      "date_updated": 1616516022,
      "date_released": 0,
      "date_policy_start": 0,
      "date_policy_end": 0
    },
    {
      "id": "H01RR4604RZ",
      "team_id": "E81A4BN3H",
      "creator_id": "WKUNKUXSL",
      "name": "First Policy",
      "description": "",
      "restrictions": [
        "NO_RESTRICTION"
      ],
      "status": "ACTIVE",
      "date_created": 1616084896,
      "date_updated": 1616517381,
      "date_released": 0,
      "date_policy_start": 0,
      "date_policy_end": 0
    }
  ],
  "policy_total_count": 2,
  "response_metadata": {
    "next_cursor": ""
  }
}

Return to method list

admin.legalHold.policies.release

This method releases an active Legal Hold policy. Released policies will no longer hold data for any custodians that fall under those policies.

Method URL: https://slack.com/api/admin.legalHold.policies.release
Required scope: admin.legalHolds:write
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
policy_id Hxxxxxxxxx Required Policy ID to release.

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "policy_id": "H01RR4604RZ"
}

Example Response

{
  "ok": true,
  "policy": {
    "id": "H01RR4604RZ",
    "team_id": "E81A4BN3H",
    "creator_id": "WKUNKUXSL",
    "name": "First Policy",
    "description": "",
    "restrictions": [
      "NO_RESTRICTION"
    ],
    "status": "RELEASED",
    "date_created": 1616084896,
    "date_updated": 1616518337,
    "date_released": 1616518337,
    "date_policy_start": 0,
    "date_policy_end": 0
  }
}

Return to method list

admin.legalHold.policies.set

This method can be used to update the details of an existing Legal Hold policy. Changes can only be made to active policies.

Method URL: https://slack.com/api/admin.legalHold.policies.set
Required scope: admin.legalHolds:write
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
policy_id Hxxxxxxxxx Required Policy ID to modify.
name Policy name Optional A textual name for the policy. This must be a unique name.
description Content under review for case xxxx Optional A long form textual description of the policy.

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "policy_id": "H01S3583Z4M",
  "description": "This policy applies to custodians in group A and B"
}

Example Response

{
    "ok": true,
    "policy": {
        "id": "H01S3583Z4M",
        "team_id": "E81A4BN3H",
        "creator_id": "WKUNKUXSL",
        "name": "Second Policy",
        "description": "This policy applies to custodians in group A and B",
        "restrictions": [
            "NO_RESTRICTION"
        ],
        "status": "ACTIVE",
        "date_created": 1616516022,
        "date_updated": 1616519107,
        "date_released": 0,
        "date_policy_start": 0,
        "date_policy_end": 0
    }
}

Return to method list

admin.legalHold.entities.add

This method associates one or more custodians (or entities) to an active Legal Hold policy.

Method URL: https://slack.com/api/admin.legalHold.entities.add
Required scope: admin.legalHolds:write
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
policy_id Hxxxxxxxxx Required Policy ID to modify.
entities [{"entity_type": "USER","entity_id":"W8V90M2U9"}] Required List if entity objects to add. Please see the Entity Types reference page for a complete list of supported entities. Only 100 entities can be added at a time. There is a max limit of 1000 active entities per Legal Hold policy.

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "policy_id": "H01RR4604RZ",
  "entities": [
    {
      "entity_type": "USER",
      "entity_id": "W8V90M2U9"
    }
  ]
}

Example Response

{
  "ok": true,
  "created_entities": [
    {
      "id": "He01RA72HZL7",
      "team_id": "E81A4BN3H",
      "policy_id": "H01RR4604RZ",
      "entity_type": "USER",
      "entity_id": "W8V90M2U9",
      "date_created": 1616085744,
      "date_deleted": 0
    }
  ],
  "failed_entities": []
}

Return to method list

admin.legalHold.entities.list

This method returns a paginated list of custodians (or entities) assigned to a Legal Hold policy.

Method URL: https://slack.com/api/admin.legalHold.entities.list
Required scope: admin.legalHolds:read
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
policy_id Hxxxxxxxxx Required Policy ID to fetch custodians (or entities) for.
cursor Hexxxxxxxxx Optional Specify to obtain the next page of results from a previous response next_cursor value.
limit 10 Optional Number of custodians (or entities) to return per page. (Max: 1000, Default: 1000)
include_deleted true Optional Specify to include/exclude deleted custodians from the response. (Default: false)

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "policy_id": "H01RR4604RZ"
}

Example Response

{
  "ok": true,
  "entities": [
    {
      "id": "He01RA72HZL7",
      "team_id": "E81A4BN3H",
      "policy_id": "H01RR4604RZ",
      "entity_type": "USER",
      "entity_id": "W8V90M2U9",
      "date_created": 1616085744,
      "date_deleted": 0
    }
  ],
  "response_metadata": {
    "next_cursor": ""
  }
}

Return to method list

admin.legalHold.entities.remove

This method removes one or more custodians (or entities) from an active Legal Hold policy.

Method URL: https://slack.com/api/admin.legalHold.entities.remove
Required scope: admin.legalHolds:write
HTTP Method: POST

Argument Example Required Description
token xxxx-xxxxxxxxx-xxxx Required Authentication token bearing required scopes.
policy_id Hxxxxxxxxx Required Policy ID to modify.
ids ["Hexxxxxxxxx","Hexxxxxxxxx"] Required List of entity IDs to remove from the policy. IDs can be found using the entities list method. Only 100 entities can be removed at a time.

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "policy_id": "H01RR4604RZ",
  "ids": ["He01RA72HZL7"]
}

Example Response

{
    "ok": true,
    "failed_ids": []
}

Return to method list