---
title: "POST /v1/matters/{matterId}/holds"
method: POST
path: "/v1/matters/{matterId}/holds"
tags: ["matters"]
---

# POST /v1/matters/{matterId}/holds

`POST /v1/matters/{matterId}/holds`

Creates a hold in the specified matter.

## Path parameters

- `matterId` string, required

## Request body

- Hold — A hold. A hold prevents the specified Google Workspace service from purging data for specific accounts or all members of an organizational unit. To work with Vault resources, the account must have the [required Vault privileges] (https://support.google.com/vault/answer/2799699) and access to the matter. To access a matter, the account must have created the matter, have the matter shared with them, or have the **View All Matters** privilege.
  - `name` string — The name of the hold.
  - `accounts` HeldAccount[] — If set, the hold applies to the specified accounts and **orgUnit** must be empty.
    - `accountId` string — The account ID, as provided by the [Admin SDK](https://developers.google.com/admin-sdk/).
    - `holdTime` string, google-datetime — Output only. When the account was put on hold.
    - `email` string — The primary email address of the account. If used as an input, this takes precedence over **accountId**.
    - `firstName` string — Output only. The first name of the account holder.
    - `lastName` string — Output only. The last name of the account holder.
  - `holdId` string — The unique immutable ID of the hold. Assigned during creation.
  - `updateTime` string, google-datetime — The last time this hold was modified.
  - `orgUnit` HeldOrgUnit — The organizational unit covered by a hold. This structure is immutable.
    - `orgUnitId` string — The organizational unit's immutable ID as provided by the [Admin SDK](https://developers.google.com/admin-sdk/).
    - `holdTime` string, google-datetime — When the organizational unit was put on hold. This property is immutable.
  - `corpus` 'CORPUS_TYPE_UNSPECIFIED' | 'DRIVE' | 'MAIL' | 'GROUPS' | 'HANGOUTS_CHAT' | 'VOICE' | 'CALENDAR' | 'GEMINI' — The service to be searched.
  - `query` CorpusQuery — Service-specific options for holds.
    - `calendarQuery` HeldCalendarQuery — Options for Calendar holds.
    - `mailQuery` HeldMailQuery — Query options for Gmail holds.
      - `endTime` string, google-datetime — The end time for the query. Specify in GMT. The value is rounded to 12 AM on the specified date.
      - `startTime` string, google-datetime — The start time for the query. Specify in GMT. The value is rounded to 12 AM on the specified date.
      - `terms` string — The [search operators](https://support.google.com/vault/answer/2474474) used to refine the messages covered by the hold.
    - `driveQuery` HeldDriveQuery — Options for Drive holds.
      - `includeTeamDriveFiles` boolean — To include files in Team Drives in the hold, set to **true**.
      - `includeSharedDriveFiles` boolean — To include files in shared drives in the hold, set to **true**.
    - `groupsQuery` HeldGroupsQuery — Query options for group holds.
      - `endTime` string, google-datetime — The end time for the query. Specify in GMT. The value is rounded to 12 AM on the specified date.
      - `startTime` string, google-datetime — The start time for the query. Specify in GMT. The value is rounded to 12 AM on the specified date.
      - `terms` string — The [search operators](https://support.google.com/vault/answer/2474474) used to refine the messages covered by the hold.
    - `voiceQuery` HeldVoiceQuery — Options for Voice holds.
      - `coveredData` string[] — A list of data types covered by the hold. Should be non-empty. Order does not matter and duplicates are ignored.
    - `geminiQuery` HeldGeminiQuery — Options for Gemini holds.
    - `hangoutsChatQuery` HeldHangoutsChatQuery — Options for Chat holds.
      - `includeRooms` boolean — To include messages in Chat spaces the user was a member of, set to **true**.

## Response `200`

Successful response

---

[API](https://skmtc.dev/google/apis/vault.md) · [All operations](https://skmtc.dev/google/apis/vault/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/google/vault/revisions/db6937065136/schema)