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

# Client Matters

> Manage billing attribution and access control for legal work

The Client Matter API allows you to programmatically create, retrieve, and remove client-matter associations in Harvey. This enables alignment of usage and query activity with specific billing codes, legal engagements, or internal projects.

<Note>
  The current API request rate limits for Client Matter API endpoints are **150 requests per minute**.
</Note>

```bash theme={null}
POST /api/v1/client_matters
GET /api/v1/client_matters
DELETE /api/v1/client_matters
```

## Overview

Use the Client Matter API to:

* **Track Usage by Client Matter**: Attribute usage to specific clients or matters
* **Streamline Onboarding**: Bulk upload client-matter lists during rollout
* **Maintain Clean Data**: Deactivate unused or outdated entries

***

## Endpoints

### Add or Update Client Matters

```bash theme={null}
POST /client_matters
```

```bash theme={null}
curl -X POST https://api.harvey.ai/api/v1/client_matters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_matters": [
      {
        "cm_name": "M-2024-0034",
        "cm_desc": "Doe vs. Smith",
        "cm_allowed": "true"
      },
      {
        "cm_name": "M-2025-0094",
        "cm_desc": "Fisher vs. Smith",
        "cm_allowed": "false"
      }
    ]
  }'
```

### List Existing Client Matters

```bash theme={null}
GET /client_matters
```

```bash theme={null}
curl -X GET https://api.harvey.ai/api/v1/client_matters \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Delete Client Matters

```bash theme={null}
DELETE /client_matters
```

```bash theme={null}
curl -X DELETE https://api.harvey.ai/api/v1/client_matters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_matters": ["M-2024-0035"]
  }'
```

***

## Use Cases

### Use Case 1: Bulk Onboarding of Client Matters

**Challenge**: Large firms need to load thousands of client-matter combinations before go-live.

**Solution**: Use the POST endpoint to upload up to 10,000 entries at once.

### Use Case 2: Enforcing Scope-Based Access

**Challenge**: Admins need to ensure users only access work linked to authorized matters.

**Solution**: Sync client-matter assignments with workspace or group-level permissions.

### Use Case 3: Cleaning Up Inactive Matters

**Challenge**: Outdated entries clutter reporting and can lead to billing confusion.

**Solution**: Use the DELETE endpoint to retire no-longer-used matter IDs.

***

## Best Practices

* **Normalize naming**: Ensure consistent `client_id`, `matter_id`, and `name` conventions across systems
* **Automate imports**: Tie the POST endpoint to your firm’s intake or billing system
* **Verify before deletion**: Always run a `GET` call before using DELETE to confirm matter IDs
* **Track usage attribution**: Cross-reference matter IDs in `/history/usage` and `/history/query` responses
* **Use clear naming**: Populate the `name` field with a human-readable description for internal clarity

## Error Handling

| Status Code | Description                             | Example Error Message                    |
| ----------- | --------------------------------------- | ---------------------------------------- |
| 200         | Success                                 | N/A                                      |
| 400         | Bad Request – Invalid format            | `{ "error": "Missing client_id" }`       |
| 401         | Unauthorized – Invalid API key          | `{ "error": "Unauthorized" }`            |
| 429         | Too Many Requests – Rate limit exceeded | `{ "error": "Rate limit exceeded" }`     |
| 500         | Internal Server Error                   | `{ "error": "Unexpected server error" }` |

***

Need help getting started? Contact your Harvey Customer Success Manager for more information.