Docs
Tutorials
Developer Program
Your apps

Legal Holds API 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.

OAuth Scopes

For the best customer experience, please instruct the Org Owner to log into their Slack organization within their browser before initiating the OAuth flow. If not, the expected behavior is that the user will be logged into their organization without the redirect.

Scope Related Methods
admin.legal_holds:read admin.legalHolds.policies.info, admin.legalHolds.policies.list, admin.legalHolds.entities.list
admin.legal_holds:write admin.legalHolds.policies.activate, admin.legalHolds.policies.create, admin.legalHolds.policies.release, admin.legalHolds.policies.set, admin.legalHolds.entities.add, admin.legalHolds.entities.remove

Methods

Policies

When creating a new Legal Hold policy, the API method caller can specify one or more restrictions to apply to the policy. These restrictions modify the data which is held to include or exclude customer created content.

Restriction Description
NO_RESTRICTION The policy does not define any restrictions and data will be held for all relevant conversations.
ONLY_DMS The policy will only apply to conversations occuring in direct message channels only. All other conversations will not be considered by this policy.

Use these methods to define and manage Legal Hold policies.

Custodians

In order for a Legal Hold policy to retain customer data, a policy must define one or more entities. Entities attach to policies and specify which types of content are to be held.

Entity Type Entity ID Description
USER Encoded user ID Hold message data authored by or visible to the specified user. This includes message data sent in conversations the user was previously a member of.

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.

This method accepts a cursor parameter for pagination. When paginating, these values will be returned as next_cursor value located within the response_metadata object of the response.

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.

This method accepts a cursor parameter for pagination. When paginating, these values will be returned as next_cursor value located within the response_metadata object of the response.

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

Errors

The following errors may be returned from the API.

Error Description
invalid_cursor The pagination cursor provided is invalid. Please use the next_cursor value from a previous request response only.
legal_hold_not_found The requested policy does not exist. Check that the policy ID provided is valid.
released_policy_edit_not_allowed Polices which are released cannot be edited.
too_many_entities The request cannot be completed because it includes too many entities. Retry the request with a smaller number of entities.
max_active_entities_reached A legal hold policy can have up to 1000 entities. Try reducing the number of entities being added.
unknown_method The requested method cannot be found. You will see this error if the Legal Holds API is enabled, but your token does not have admin.legalHolds:* scopes.