Step 2: Create and manage cases

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "Partner APIs MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}
Close

A case is the container for everything else. Extraction codes and exports always belong to a case.


Creating a case and starting an export need an active plan on your organization. Without one, those calls are refused with 403. If you see this on a new organization, contact Hearsay; do not retry.

Create a case

POST /case

  • Required: name. dueDate is optional.
  • Common optional fields: description, matterId (your own client or matter reference; it is printed on invoices), priority (low, medium, high, urgent), status (open, closed, archived, pending), tags and metadata.
  • The caller becomes the case owner.
  • The response wraps the case with its members and counts. Save the case id from data.case.id; every later step needs it.
  • Optional shortcut: the same call can create the first extraction code. Set createExtractionCode to true and fill in the custodian fields (custodianName, custodianEmail, custodianPhone, requestedSources, sendEmail). For a clear, auditable flow, we recommend creating the case first and the code separately (Step 3).

Update a case

PATCH /case/{caseId}

  • You can change name, description, matterId, status, priority, metadata and tags.
  • Send only the fields you want to change.
  • Renaming a case also changes its slug. Always refer to cases by id, never by name or slug.

List and read cases

  • GET /case lists the cases the user can see in the organization from the header, most recently updated first. Filters include searchText, status, priority, tags and isArchived. Each row holds the case under case, so a case id is at data.data[].case.id. Page through the results as described in "Rules for every call".
  • The list can include cases another firm shared with you. Check that a case belongs to the work you were given before you act on it.
  • GET /case/{caseId} returns one case with its members, pending invitations, active extraction codes and conversation count.

Create a case:

curl -X POST "https://api.usehearsay.com/case" \
  -H "Authorization: Bearer $TOKEN" \
  -H "organization: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Doe v. Example Corp",
    "dueDate": "2026-11-30T00:00:00.000Z",
    "matterId": "MAT-0042",
    "priority": "medium"
  }'

The case id is data.case.id:

{
  "data": {
    "case": {
      "id": "507f1f77bcf86cd799439011",
      "name": "Doe v. Example Corp",
      "slug": "doe-v-example-corp",
      "matterId": "MAT-0042",
      "priority": "medium"
    },
    "usersWithAccess": [],
    "extractionCodes": [],
    "totalExtractionCodes": 0,
    "conversationsCount": 0
  },
  "statusCode": 201,
  "timestamp": "2026-01-15T10:15:00.000Z"
}