Client Matters

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.

The current API request rate limits for Client Matter API endpoints are 150 requests per minute.

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

POST /client_matters

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

GET /client_matters

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

Delete Client Matters

DELETE /client_matters

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.

Getting Started

Endpoint Overview

MCP (Beta)

Client Matters

Overview

Endpoints

Add or Update Client Matters

List Existing Client Matters

Delete Client Matters

Use Cases

Use Case 1: Bulk Onboarding of Client Matters

Use Case 2: Enforcing Scope-Based Access

Use Case 3: Cleaning Up Inactive Matters

Best Practices

Error Handling

​Overview

​Endpoints

​Add or Update Client Matters

​List Existing Client Matters

​Delete Client Matters

​Use Cases

​Use Case 1: Bulk Onboarding of Client Matters

​Use Case 2: Enforcing Scope-Based Access

​Use Case 3: Cleaning Up Inactive Matters

​Best Practices

​Error Handling

Overview

Endpoints

Add or Update Client Matters

List Existing Client Matters

Delete Client Matters

Use Cases

Use Case 1: Bulk Onboarding of Client Matters

Use Case 2: Enforcing Scope-Based Access

Use Case 3: Cleaning Up Inactive Matters

Best Practices

Error Handling