Skip to main content
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 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.