Legal Holds API Reference

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.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

Entity Types

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.


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.


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.


Methods within the Legal Holds API support pagination use one of two terms as the pagination key. Supported methods accept 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 Pagination Key
admin.legalHolds.policies.list cursor
admin.legalHolds.entities.list cursor