> ## Documentation Index > Fetch the complete documentation index at: https://developers.harvey.ai/llms.txt > Use this file to discover all available pages before exploring further. # Delete Matters > Soft-deletes matters by your firm's client and matter identifiers. Submit 1 to 10,000 pairs per request. Each pair receives one result in deleted, already_absent, or errors. Inspect errors even when the response is HTTP 200. Missing and already-deleted matters appear in already_absent. Externally linked matters cannot be deleted while ethical-wall enforcement is enabled. The parent client is kept. Deleting a matter does not delete historical queries associated with that matter, nor does it remove the matter from those historical queries. ### Permissions Requires **Client matters admin** (`write:client_matters`). ### Matching Send the `client_id` and `matter_id` you use with `POST /api/v2/matters`. Do not send the full matter name or `harvey_id`. Harvey trims leading and trailing whitespace from both identifiers. Matching uses the identifier pair first, then the stored name: `client_id` + the delimiter + `matter_id`. This finds matters created through v1. Deleted matters also match. The API uses the delimiter configured for the token's active workspace, or `.` when it is unset or blank. This endpoint never returns `delimiter_required`, and the workspace's name format does not apply. ### Results Each pair appears once in the response: in `deleted`, `already_absent`, or `errors`. `deleted` and `already_absent` return the trimmed identifiers. `errors` echoes the values you sent. A pair with no matching matter, including a pair whose client does not exist, appears in `already_absent`. So does a matter that was already deleted. These are successful results, so a repeated request is safe. A pair that repeats an earlier pair after trimming fails with `duplicate_pair`; Harvey processes the earlier pair as usual. Externally linked matters, such as matters synced from a DMS or an ethical-wall provider, fail with `blocked_by_ethical_wall` while ethical-wall enforcement is enabled for the workspace. Deleting a matter keeps its parent client and its ethical-wall configuration. A later `POST /api/v2/matters` with the same pair restores the matter. See the [Client Matters guide](/guides/client_matters#delete-matters) for examples and error handling. ## OpenAPI ````yaml /client_matters_api.json delete /api/v2/matters openapi: 3.0.1 info: title: Harvey Client Matter API description: >- Create and update clients and matters by your firm identifiers, and delete matters by the same identifiers. List client matters through the v1 endpoint. version: 1.0.0 contact: email: support@harvey.ai servers: - url: https://api.harvey.ai description: Harvey API server security: [] paths: /api/v2/matters: delete: tags: - Delete summary: Delete Matters description: >- Soft-deletes matters by your firm's client and matter identifiers. Submit 1 to 10,000 pairs per request. Each pair receives one result in deleted, already_absent, or errors. Inspect errors even when the response is HTTP 200. Missing and already-deleted matters appear in already_absent. Externally linked matters cannot be deleted while ethical-wall enforcement is enabled. The parent client is kept. Deleting a matter does not delete historical queries associated with that matter, nor does it remove the matter from those historical queries. operationId: deleteMatters requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeleteMattersRequest' example: matters: - client_id: '10022421' matter_id: M001 - client_id: '10022421' matter_id: M002 responses: '200': description: Per-pair results for the submitted matters. content: application/json: schema: $ref: '#/components/schemas/DeleteMattersResponse' examples: deleted: summary: Deleted matter value: deleted: - client_id: '10022421' matter_id: M001 already_absent: [] errors: [] alreadyAbsent: summary: >- Missing or already-deleted matter, including a repeated request value: deleted: [] already_absent: - client_id: '10022421' matter_id: M001 errors: [] partialSuccess: summary: Valid pair succeeds while other pairs fail value: deleted: - client_id: '10022421' matter_id: M001 already_absent: [] errors: - client_id: '10022421' matter_id: M002 error: blocked_by_ethical_wall detail: The matter is managed by an external wall provider - client_id: '10022421' matter_id: ' M001 ' error: duplicate_pair detail: >- This client and matter pair appears earlier in the batch '400': description: >- The request was rejected as a whole and no matters were deleted: invalid_request, or too_many_items for more than 10,000 pairs. content: application/json: schema: $ref: '#/components/schemas/ClientMatterBatchError' examples: invalidRequest: summary: Unknown field in the request body value: error: invalid_request detail: Invalid request body validation_errors: - loc: - client_ids type: extra_forbidden tooManyItems: summary: More than 10,000 pairs value: error: too_many_items detail: Too many items in one request '401': description: >- Missing, invalid, or expired API token, or missing write:client_matters permission. '403': description: Forbidden. '429': description: >- Rate limit exceeded. These endpoints share the client matter rate limit, which defaults to 150 requests per minute per workspace. '500': description: Internal server error. security: - bearerAuth: [] components: schemas: DeleteMattersRequest: type: object description: >- Submit explicit client_id and matter_id pairs. Unknown fields return HTTP 400 with invalid_request. required: - matters properties: matters: type: array minItems: 1 maxItems: 10000 items: $ref: '#/components/schemas/DeleteMatterInput' additionalProperties: false DeleteMattersResponse: type: object required: - deleted - already_absent - errors properties: deleted: type: array description: Matters deleted by this request. items: $ref: '#/components/schemas/DeletedMatter' already_absent: type: array description: Missing or already-deleted matters. These are successful results. items: $ref: '#/components/schemas/DeletedMatter' errors: type: array items: $ref: '#/components/schemas/DeleteMatterError' ClientMatterBatchError: type: object description: Body of a 400 response from `/api/v2/clients` and `/api/v2/matters`. required: - error - detail properties: error: $ref: '#/components/schemas/ClientMatterBatchErrorCode' detail: type: string description: Human-readable explanation. validation_errors: type: array description: Present for `invalid_request`. Field values are never echoed. items: $ref: '#/components/schemas/ClientMatterFieldError' DeleteMatterInput: type: object required: - client_id - matter_id properties: client_id: type: string description: >- The firm's client identifier, the client_id used in v2 upserts. Not the Harvey client UUID. matter_id: type: string description: >- The firm's matter identifier, the matter_id used in v2 upserts. Not the Harvey matter UUID (harvey_id) or the full stored name. additionalProperties: false DeletedMatter: type: object required: - client_id - matter_id properties: client_id: type: string description: client_id after trimming surrounding whitespace. matter_id: type: string description: matter_id after trimming surrounding whitespace. DeleteMatterError: type: object required: - client_id - matter_id - error - detail properties: client_id: type: string description: Echoes the raw request value. matter_id: type: string description: Echoes the raw request value. error: $ref: '#/components/schemas/DeleteMatterErrorCode' detail: type: string description: Human-readable explanation. ClientMatterBatchErrorCode: type: string description: >- Stable code for a rejected request. too_many_items: more than 10,000 rows. invalid_request: invalid request shape, empty batch, missing required field, wrong type, allowed set to null, or a token user that cannot be found. delimiter_required: POST /api/v2/matters requires an explicit delimiter for the active workspace, but none is configured. Other workspaces use `.` when no delimiter is configured. POST /api/v2/clients and DELETE /api/v2/matters do not emit delimiter_required. Duplicate identifiers and length limits on text fields produce per-row errors instead. enum: - too_many_items - invalid_request - delimiter_required ClientMatterFieldError: type: object required: - loc - type properties: loc: type: array description: >- Path to the offending field. Each entry is a string naming a field or an integer indexing an array. items: {} type: type: string description: The validation failure kind, for example `missing` or `string_type`. DeleteMatterErrorCode: type: string description: >- Stable code for a pair that was not deleted. invalid_client_id and invalid_matter_id mean the identifier is empty after trimming. duplicate_pair means the pair repeats an earlier pair in the batch after trimming. identity_conflict means the stored matter does not uniquely match this pair. name_collision means different pairs in the batch resolve to the same matter by stored name. blocked_by_ethical_wall means the matter is externally linked and ethical-wall enforcement is enabled for the workspace. Each failed pair reports one error. enum: - invalid_client_id - invalid_matter_id - duplicate_pair - identity_conflict - name_collision - blocked_by_ethical_wall securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Token ```` ## Related topics - [Client Matters](/guides/client_matters.md) - [Delete Client Matters](/api-reference/delete/delete-client-matters.md) - [Upsert Matters](/api-reference/upsert/upsert-matters.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.