Response Format

All API responses use a consistent JSON envelope.

Success Responses

{
  "success": true,
  "data": {
    "id": "case_abc123",
    "name": "Smith v. Johnson",
    "plaintiff_name": "John Smith"
  }
}

Field	Type	Description
success	boolean	true for successful requests
data	object	The response payload — structure varies by endpoint

Error Responses

{
  "success": false,
  "error": "case_id is required",
  "error_code": "case_id_missing",
  "error_type": "invalid_request_error",
  "request_id": "req_abc123"
}

Field	Type	Description
success	boolean	false for error responses
error	string	Human-readable error message
error_code	string	Machine-readable error code — switch on this
error_type	string	Error category for generic handling
error_param	string	Present when the error relates to a specific field
request_id	string	Unique ID for debugging with support

See Error Handling for the full error code catalog.

Parsing Responses

Python

resp = requests.post(f"{BASE_URL}/api/cases", headers=headers, json=body)
result = resp.json()

if result["success"]:
    case_id = result["data"]["case"]["id"]
    print(f"Created case: {case_id}")
else:
    print(f"Error: {result['error']} ({result['error_code']})")

TypeScript

const resp = await fetch(`${BASE_URL}/api/cases`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify(body),
});
const result = await resp.json();

if (result.success) {
  const caseId = result.data.case.id;
  console.log(`Created case: ${caseId}`);
} else {
  console.error(`Error: ${result.error} (${result.error_code})`);
}

Go

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result struct {
    Success bool            `json:"success"`
    Data    json.RawMessage `json:"data"`
    Error   string          `json:"error"`
    Code    string          `json:"error_code"`
}
json.NewDecoder(resp.Body).Decode(&result)

if result.Success {
    // Parse data based on endpoint
    fmt.Println("Success")
} else {
    fmt.Printf("Error: %s (%s)\n", result.Error, result.Code)
}

Field Naming

All field names use snake_case:

{
  "case_id": "case_abc123",
  "plaintiff_name": "John Smith",
  "file_category": "vehicle_photo",
  "vehicle_role": "plaintiff",
  "created_at": "2024-01-10T14:30:00Z"
}

List Responses

List endpoints return an array in the data field:

{
  "success": true,
  "data": {
    "cases": [
      { "id": "case_abc123", "name": "Smith v. Johnson" },
      { "id": "case_def456", "name": "Doe v. Williams" }
    ]
  }
}

Request IDs

Every response includes a request_id (also in the X-Request-ID header). Include this when contacting support.

You can send your own X-Request-ID header for tracing — the API will use it as-is and echo it back.