Submitting a Case

Submit a case and its documents in a single request:

• POST /api/v1/partner/cases/create/ — one-shot multipart create + submit. Send a case part (JSON-encoded case payload, including case_type) plus attachments as files parts with optional per-file labels (same order; up to 10 files, 150 MB each, 192 MB of file bytes per request — see Size limits). Accepted file types: PDF, DOC/DOCX, XLS/XLSX, JPG/JPEG, PNG, GIF, TIFF/TIF, TXT, CSV, MSG, EML, HEIC/HEIF. HEIC/HEIF photos up to 25 MB are converted to JPEG for review; a larger photo, or one that cannot be converted, reaches review as the original file. The original is always retained. The case is always created when the JSON is valid (HTTP 201); files are best-effort and any rejected file is reported in the response — retry it via POST /api/v1/partner/cases/{case_ref}/files/.
  • Policy Existence (case_type: pe) — when you need to determine whether a defendant has insurance coverage (personal auto, commercial auto, or homeowners).
  • Policy Limit (case_type: pl) — when you already have insurance company and policy/claim information and need the coverage limits (personal auto, commercial auto, CGL, homeowners/renters, and more).

curl

curl -X POST https://api.redfolderresearch.com/api/v1/partner/cases/create/ \
  -H "Authorization: Token <your_token>" \
  -F 'case={"case_type":"pe","is_test":true,"plaintiff_name":"Jane Smith","date_of_loss":"2026-06-20","base_product":["personal_auto_policy_existence"],"search_reason":["defendant_insurance_unknown"],"is_incident_report_provided":false,"is_user_agreeing_to_all_terms_and_conditions":true,"should_exclude_other_insurance_from_search":false,"cc_emails":"paralegal@lawfirm.com","defendant_information":{"first_name":"John","last_name":"Doe","address":"123 Main St","city":"Boise","state_or_province":"ID","postal_or_zip_code":"83702"}}' \
  -F "files=@police_report.pdf" \
  -F "labels=incident_report"

Python

import json

import requests

case = {
    "case_type": "pe",
    "is_test": True,
    "plaintiff_name": "Jane Smith",
    "date_of_loss": "2026-06-20",
    "base_product": ["personal_auto_policy_existence"],
    "search_reason": ["defendant_insurance_unknown"],
    "is_incident_report_provided": False,
    "is_user_agreeing_to_all_terms_and_conditions": True,
    "should_exclude_other_insurance_from_search": False,
    "cc_emails": "paralegal@lawfirm.com",
    "defendant_information": {
        "first_name": "John",
        "last_name": "Doe",
        "address": "123 Main St",
        "city": "Boise",
        "state_or_province": "ID",
        "postal_or_zip_code": "83702",
    },
}

with open("police_report.pdf", "rb") as file_handle:
    response = requests.post(
        "https://api.redfolderresearch.com/api/v1/partner/cases/create/",
        headers={"Authorization": "Token <your_token>"},
        data={"case": json.dumps(case), "labels": "incident_report"},
        files=[("files", file_handle)],
    )

JavaScript

const casePayload = {
  case_type: "pe",
  is_test: true,
  plaintiff_name: "Jane Smith",
  date_of_loss: "2026-06-20",
  base_product: ["personal_auto_policy_existence"],
  search_reason: ["defendant_insurance_unknown"],
  is_incident_report_provided: false,
  is_user_agreeing_to_all_terms_and_conditions: true,
  should_exclude_other_insurance_from_search: false,
  cc_emails: "paralegal@lawfirm.com",
  defendant_information: {
    first_name: "John",
    last_name: "Doe",
    address: "123 Main St",
    city: "Boise",
    state_or_province: "ID",
    postal_or_zip_code: "83702",
  },
};

// fileBlob: a File (from an <input>) or Blob holding police_report.pdf
const form = new FormData();
form.append("case", JSON.stringify(casePayload));
form.append("files", fileBlob, "police_report.pdf");
form.append("labels", "incident_report");

const response = await fetch("https://api.redfolderresearch.com/api/v1/partner/cases/create/", {
  method: "POST",
  headers: { "Authorization": "Token <your_token>" },
  body: form,
});

The API validates submissions based on the product and options selected and returns clear validation messages if anything is missing — see the Conditional Requirements block on the endpoint for product-specific rules (for example, commercial-auto Policy Existence requires is_defendant_transportation_company: true).

Plaintiff (first-party) searches

By default a search is about the defendant — the at-fault party. Set "search_subject": "plaintiff" when the search is about your own client instead (for example, researching their UM/UIM or other first-party coverage). Put the client’s details in defendant_information either way — for a plaintiff search that field holds your client, not an at-fault party — and for Policy Limit, insurance_company becomes the client’s own carrier.

Policy Existence’s search_reason is optional for plaintiff searches (it stays required for defendant searches, same as today, and an explicit [] is still accepted). A defendant search submitted without search_reason now returns its 400 under non_field_errors instead of a search_reason-keyed error — same status code, just a different key in the response body.

Policy Existence, researching a client’s own coverage:

{
  "case_type": "pe",
  "is_test": true,
  "plaintiff_name": "Riley Chen",
  "date_of_loss": "2026-06-20",
  "base_product": ["personal_auto_policy_existence"],
  "search_subject": "plaintiff",
  "is_incident_report_provided": false,
  "is_user_agreeing_to_all_terms_and_conditions": true,
  "should_exclude_other_insurance_from_search": false,
  "cc_emails": "paralegal@lawfirm.com",
  "defendant_information": {
    "first_name": "Riley",
    "last_name": "Chen",
    "address": "123 Main St",
    "city": "Boise",
    "state_or_province": "ID",
    "postal_or_zip_code": "83702"
  }
}

Policy Limit, same idea — insurance_company is the client’s own carrier, and search_reason does not apply to Policy Limit either way:

{
  "case_type": "pl",
  "is_test": true,
  "plaintiff_name": "Riley Chen",
  "date_of_loss": "2026-06-20",
  "base_product": ["personal_auto_policy_limits"],
  "search_subject": "plaintiff",
  "is_incident_report_provided": false,
  "cc_emails": "paralegal@lawfirm.com",
  "insurance_company": "Acme Mutual Insurance",
  "policy_number": "POL-12345",
  "defendant_information": {
    "first_name": "Riley",
    "last_name": "Chen",
    "address": "123 Main St",
    "city": "Boise",
    "state_or_province": "ID",
    "postal_or_zip_code": "83702"
  }
}

search_subject is echoed back on GET /api/v1/partner/cases/{case_ref}/; the 201 returned by case create does not include it.

Size limits

Scope	Limit
Per file	150 MB
Per request	10 files, 192 MB of file bytes
Per case, over its lifetime	25 files, 500 MB

The per-request allowance is 192 MB rather than a round 200 MB because our network edge caps the total request body — file bytes plus multipart boundaries, part headers, and the case JSON — at 200 MB. The 8 MB difference is the overhead reserve, so a request carrying the full 192 MB of file bytes still fits under the body cap.

A single file over 150 MB is rejected with 400 and error_code: file_too_large. A create request carrying more than 10 files, or more than 192 MB of file bytes, is rejected with 400 and a files field error. An append that would push a case past 25 files or 500 MB returns 409 — see Errors. Files you send when replying to a case.action_required interaction do not count toward the per-case cap.

The limits above are the real, effective ceilings — there is no lower interim cap in front of them.

A body over 200 MB is rejected at the network edge, not by the API

Our network edge caps the total request body at 200 MB. A request over that is rejected at the edge before it reaches Red Folder, with a generic 413 or 502 that carries no Red Folder error_code and leaves no trace on your case — retrying it unchanged fails the same way. Staying within the per-request allowance above (10 files, 192 MB of file bytes) keeps you clear of it; if you are already over, use the recovery steps below.

When a file is too large to send

1. Create the case without the oversized file. The case JSON always lands on its own (HTTP 201) — attachments are best-effort and never block case creation.
2. Compress the file and/or append files one at a time via POST /api/v1/partner/cases/{case_ref}/files/. One file per request keeps each body well under the ceiling, and each append is reported independently.
3. If a single artifact still cannot be brought under the cap, email requests@redfolderresearch.com with the case ref and we will attach it for you.

Duplicate files

A file that is byte-identical to one already on the case, under the same label, is stored once. The create response reports it as accepted with the existing file_id; an append returns 201 with that same file_id and the file’s current jira_sync_state. filename in either response is always the name you sent. Files with different content, or the same content under a different label, are separate attachments.

Legacy 3-step flow (deprecated)

The original flow — POST /policy_existence_searches/ or POST /policy_limit_searches/, then POST /upload/{ticket_id}/{file_label} per file, then PUT /tickets/{ticket_id}/ready — still works for existing integrations but is deprecated. New integrations should use POST /api/v1/partner/cases/create/.