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. 
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 CodeDescriptionExample Error Message
200SuccessN/A
400Bad Request – Invalid format{ "error": "Missing client_id" }
401Unauthorized – Invalid API key{ "error": "Unauthorized" }
429Too Many Requests – Rate limit exceeded{ "error": "Rate limit exceeded" }
500Internal Server Error{ "error": "Unexpected server error" }
Need help getting started? Contact your Harvey Customer Success Manager for more information.