Client Matters

Use the Client Matters API to sync your firm’s client and matter identifiers with Harvey. Create clients first, then create, update, or delete their matters. To delete a client, delete its matters first. Use the v1 endpoint to list matters.

Action	Endpoint
Create or update clients	`POST /api/v2/clients`
Create or update matters	`POST /api/v2/matters`
Delete matters	`DELETE /api/v2/matters`
Delete clients	`DELETE /api/v2/clients`
List matters, including deleted matters	`GET /api/v1/client_matters`

These endpoints share a rate limit that defaults to 150 requests per minute per workspace. Each v2 request accepts 1 to 10,000 rows. Always check the errors array in the v2 response, even when the request returns HTTP 200.

Before you start

Use an API bearer token with Client matters admin (write:client_matters) to create, update, or delete records. To list matters, either this permission or Access client matters (read:client_matters) is sufficient. If your workspace has matters previously created using full names, you must explicitly set the workspace delimiter before using the v2 APIs. Set it to the separator used in those names. For an existing name such as 10022421-M001, set the delimiter to - and send client_id: "10022421" and matter_id: "M001". Harvey joins client_id, the workspace delimiter, and matter_id to form a full matter name. The examples below use .: client 10022421 and matter M001 form 10022421.M001. The v1 list API returns this full name as name, and the v1 delete API accepts it. The optional client_name and matter_name fields are display labels, such as Acme Corp and Acme Acquisition.

Create or update a client

curl -X POST https://api.harvey.ai/api/v2/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clients": [
      {"client_id": "10022421", "client_name": "Acme Corp"}
    ]
  }'

A new client appears in created:

{
  "created": [{"client_id": "10022421", "client_name": "Acme Corp"}],
  "updated": [],
  "errors": []
}

To update a client, send its client_id again with the fields you want to change. The response includes the client in updated, even if the values are unchanged. If the client was deleted, the request restores it. Restoring a client does not restore its deleted matters; restore those through POST /api/v2/matters.

Create or update a matter

Create or restore the client before sending its matters. This endpoint does not create missing clients.

curl -X POST https://api.harvey.ai/api/v2/matters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matters": [
      {
        "client_id": "10022421",
        "matter_id": "M001",
        "matter_name": "Acme Acquisition",
        "description": "Acquisition due diligence",
        "notice": "Confirm the engagement before selecting this matter."
      }
    ]
  }'

{
  "created": [
    {
      "client_id": "10022421",
      "matter_id": "M001",
      "client_name": "Acme Corp",
      "matter_name": "Acme Acquisition",
      "description": "Acquisition due diligence",
      "allowed": true,
      "notice": "Confirm the engagement before selecting this matter.",
      "harvey_id": "018d856f-0664-772c-9ed9-b2316fd881d3"
    }
  ],
  "updated": [],
  "errors": []
}

To update a matter, send the same client_id and matter_id with the fields you want to change. Harvey first looks for that pair of identifiers. If it finds no match, it checks for a matter with the same full name, such as 10022421.M001. This lets the request update a matter created through v1. The matched matter appears in updated and keeps its harvey_id. If it was deleted, the request restores it. harvey_id is the matter’s ID in Harvey.

Update or clear fields

Field	Omitted from an update	`null` or blank text	Limit
`client_name`	Keep the client label	Clear the label	256 characters
`matter_name`	Keep the matter label	Clear the label	256 characters
`description`	Keep the description	Clear the description	200 characters
`notice`	Keep the selection notice	Clear the notice	2,000 characters

For a new record, these fields default to null when omitted. client_id must contain 1 to 128 characters, and matter_id must not be empty. The full matter name (client_id + delimiter + matter_id, such as 10022421.M001) must contain at most 128 characters and match the format configured for the workspace, if any. For example, this request clears the notice and keeps the matter’s other fields:

{
  "matters": [{"client_id": "10022421", "matter_id": "M001", "notice": null}]
}

allowed follows separate rules:

Omit it to preserve an existing value. New matters default to true.
Sending it requires use:disallowed_client_matters, even when setting it to true. Without that permission, the whole request returns HTTP 403.
Use a JSON boolean (true or false), not a string. With the required permission, null returns HTTP 400 with invalid_request.

Handle batch results and errors

Each HTTP 200 response from POST /api/v2/clients or POST /api/v2/matters has three arrays: created, updated, and errors. An error in one row does not block valid rows in the same request. For example, a batch can update one matter while rejecting another whose client does not exist:

{
  "created": [],
  "updated": [
    {
      "client_id": "10022421",
      "matter_id": "M001",
      "client_name": "Acme Corp",
      "matter_name": "Acme Acquisition",
      "description": "Acquisition due diligence",
      "allowed": true,
      "notice": null,
      "harvey_id": "018d856f-0664-772c-9ed9-b2316fd881d3"
    }
  ],
  "errors": [
    {
      "client_id": "UNKNOWN",
      "matter_id": "M002",
      "error": "client_not_found",
      "detail": "No client with this identifier exists in the workspace"
    }
  ]
}

Use error codes to handle failures in your integration. The detail field explains the error in plain language. Correct failed rows before retrying them.

Row error	What to check
`invalid_client_id`, `invalid_matter_id`	IDs must not be blank; client IDs must contain at most 128 characters.
`duplicate_client_id`, `duplicate_pair`	A later row repeats a client ID or client and matter pair. Harvey ignores leading and trailing whitespace when comparing identifiers. Submit each client ID or pair once per batch.
`client_not_found`	Create or restore the parent client first.
`invalid_client_name`, `invalid_matter_name`, `description_too_long`, `notice_too_long`	Shorten the affected text.
`name_too_long`, `name_failed_workspace_regex`	Check the full matter name (`client_id` + delimiter + `matter_id`).
`name_collision`, `identity_conflict`	Different identifier pairs produce the same full matter name, or conflict with an existing record. Check the identifiers and delimiter.

Errors that affect the whole request use these HTTP status codes:

HTTP status	Meaning
400	`invalid_request` for an empty batch, missing field, or wrong type; `too_many_items` for more than 10,000 rows; `delimiter_required` when a matter request needs an explicit workspace delimiter.
401	Missing, invalid, or expired API token, or missing `write:client_matters` permission.
403	Sending `allowed` without `use:disallowed_client_matters` permission.
429	Shared client matter rate limit exceeded.
500	Internal server error.

POST /api/v2/matters uses the delimiter from the API token’s active workspace. If it is unset or empty, the endpoint uses . unless the workspace requires an explicit delimiter. When an explicit delimiter is required but missing, the endpoint returns HTTP 400:

{
  "error": "delimiter_required",
  "detail": "Set a client matter delimiter for this workspace before upserting matters"
}

Harvey does not create or update any matters in this batch. Set the workspace delimiter and retry. POST /api/v2/clients does not return this error.

Delete matters

Send the same client_id and matter_id pairs that you use with POST /api/v2/matters. Do not send the full matter name, the matter label, or harvey_id.

curl -X DELETE https://api.harvey.ai/api/v2/matters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matters": [
      {"client_id": "10022421", "matter_id": "M001"},
      {"client_id": "10022421", "matter_id": "M002"}
    ]
  }'

Each pair appears once in the response, in deleted, already_absent, or errors. In this example, the request deletes M001, and M002 does not exist:

{
  "deleted": [{"client_id": "10022421", "matter_id": "M001"}],
  "already_absent": [{"client_id": "10022421", "matter_id": "M002"}],
  "errors": []
}

deleted: the request deleted the matter.
already_absent: no matter matches the pair, or the matter was already deleted. This is a successful result, so you can safely repeat a request. A pair whose client does not exist also appears here.
errors: the request did not delete the matter. An error in one pair does not block the other pairs in the request.

deleted and already_absent return the identifiers without leading and trailing whitespace. Each entry in errors echoes the values you sent. Harvey first looks for the pair of identifiers. If it finds no match, it checks for a matter with the same full name, such as 10022421.M001. This lets the request delete a matter created through v1. The endpoint uses the delimiter from the API token’s active workspace, or . if the delimiter is unset or blank. It never returns delimiter_required, and the workspace’s name format does not apply to deletes.

Row error	What to check
`invalid_client_id`, `invalid_matter_id`	IDs must not be blank.
`duplicate_pair`	A later pair repeats an earlier client and matter pair. Harvey ignores leading and trailing whitespace when comparing identifiers. It processes the first pair and rejects the repeats. Submit each pair once per batch.
`identity_conflict`	The stored matter does not uniquely match this pair. For example, the matter with the matching full name has a different client or matter identifier. Check the identifiers and delimiter.
`name_collision`	Different pairs in the batch resolve to the same matter by full name. For example, with the `.` delimiter, client `A.B` with matter `C` and client `A` with matter `B.C` both produce `A.B.C`.
`blocked_by_ethical_wall`	The matter is externally linked, such as a matter synced from a DMS or an ethical-wall provider, and the workspace enforces ethical walls. Harvey does not delete these matters through the API.

A request with more than 10,000 pairs returns HTTP 400 with too_many_items. An empty batch, a missing field, a wrong type, or an unknown field returns HTTP 400 with invalid_request. In both cases, Harvey deletes no matters. Deleting a matter prevents users from selecting it. It does not remove past queries or their links to the matter. Harvey keeps the parent client and the matter’s ethical-wall configuration. A later request to POST /api/v2/matters with the same pair restores the matter. To delete the client after its matters, see Delete clients.

Delete clients

Delete a client’s matters with DELETE /api/v2/matters before you delete the client. This endpoint does not delete or change matters. A client that still has a matter fails with client_has_matters. Send the client_id values that you use with POST /api/v2/clients. Do not send the client label (client_name) or the Harvey client UUID.

curl -X DELETE https://api.harvey.ai/api/v2/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_ids": ["10022421", "10022422"]
  }'

Each identifier appears once in the response, in deleted, already_absent, or errors. In this example, the request deletes 10022421, and 10022422 does not exist:

{
  "deleted": [{"client_id": "10022421"}],
  "already_absent": [{"client_id": "10022422"}],
  "errors": []
}

deleted: the request deleted the client.
already_absent: no client matches the identifier, or the client was already deleted. This is a successful result, so you can safely repeat a request.
errors: the request did not delete the client. An error for one identifier does not block the other identifiers in the request.

Within each array, results keep the order of the request. deleted and already_absent return the identifiers without leading and trailing whitespace. Each entry in errors echoes the value you sent.

Row error	What to check
`invalid_client_id`	The ID must not be blank.
`duplicate_client_id`	A later identifier repeats an earlier client ID. Harvey ignores leading and trailing whitespace when comparing identifiers. It processes the first identifier and rejects the repeats. Submit each client ID once per batch.
`client_has_matters`	The client has at least one matter that is not deleted. This includes matters with `allowed` set to `false`. Delete those matters with `DELETE /api/v2/matters`, then retry. A matter that fails with `blocked_by_ethical_wall` stays, so its client also stays.

For example, this response deletes one client and rejects a client that still has a matter:

{
  "deleted": [{"client_id": "10022421"}],
  "already_absent": [],
  "errors": [
    {
      "client_id": "10022422",
      "error": "client_has_matters",
      "detail": "Delete the client’s active matters before deleting the client"
    }
  ]
}

A request with more than 10,000 client IDs returns HTTP 400 with too_many_items. An empty list, a missing field, a wrong type, or an unknown field returns HTTP 400 with invalid_request. In both cases, Harvey deletes no clients. A later request to POST /api/v2/clients with the same client_id restores the client. Restoring a client does not restore its deleted matters. Restore those through POST /api/v2/matters.

List matters

GET /api/v1/client_matters is the only endpoint that lists matters. The list includes deleted matters and usage statistics:

curl https://api.harvey.ai/api/v1/client_matters \
  -H "Authorization: Bearer YOUR_API_KEY"

The response contains a client_matters array. Each row uses these identifiers:

Field	Meaning
`id`	The Harvey matter UUID, returned by v2 as `harvey_id`.
`matter_number`	Your firm’s matter identifier. May be `null` for legacy matters.
`client_id`	The Harvey client UUID. May be `null` for legacy matters.

The v2 endpoints expect your firm’s client identifier in client_id. Do not pass the Harvey client UUID returned by this list endpoint.

Migrate from v1 writes

POST /api/v1/client_matters is deprecated. To migrate to v2:

Explicitly set the workspace delimiter to match your existing full matter names. For example, for cm_name: "10022421-M001", configure - and use client_id: "10022421" with matter_id: "M001". Joining these identifiers with the delimiter must reproduce the existing name so Harvey can match the matter.
Create or update each client with POST /api/v2/clients.
Create or update its matters with POST /api/v2/matters. Map cm_desc to description. If you send cm_allowed, map it to the JSON boolean allowed and ensure the token has use:disallowed_client_matters permission.
Handle created, updated, and errors instead of v1’s success_count and failed.

DELETE /api/v1/client_matters still deletes matters by full name. To delete by identifiers, send client_id and matter_id pairs to DELETE /api/v2/matters. Handle deleted, already_absent, and errors instead of success_count and failed. To delete clients, send their client_id values to DELETE /api/v2/clients after you delete their matters. client_name and matter_name are optional labels; they do not replace the identifiers. notice is available through the v2 matter endpoint. Continue using GET /api/v1/client_matters to list matters.

Getting Started

Endpoint Overview

MCP (Beta)

Client Matters

Before you start

Create or update a client

Create or update a matter

Update or clear fields

Handle batch results and errors

Delete matters

Delete clients

List matters

Migrate from v1 writes

​Before you start

​Create or update a client

​Create or update a matter

​Update or clear fields

​Handle batch results and errors

​Delete matters

​Delete clients

​List matters

​Migrate from v1 writes

Before you start

Create or update a client

Create or update a matter

Update or clear fields

Handle batch results and errors

Delete matters

Delete clients

List matters

Migrate from v1 writes