← API Docs|

API Changelog

API Changelog

Get the latest updates and improvements to our API.

v2.8.0Fixed

July 18, 2026

Commercial Policy Existence cancellation fee corrected to $375

Commercial Policy Existence cancellations are now quoted and billed at the published $375.00 commercial cancellation fee. Personal Policy Existence and Policy Limits cancellation fees are unchanged.

  • Commercial Policy Existence cancellation fee: cancelling a dispatched commercial Policy Existence case now quotes and bills 375.00 (the fee published in our Terms & Conditions), with fee.description of Policy Existence: Commercial Cancellation Fee. Previously the personal fee (270.00) was quoted and the difference was corrected on the invoice after the fact.
  • Compatibility: no schema changes. The cancellation quote (GET case detail) and POST /cancel responses carry the same fields; only the amount and description for commercial Policy Existence cases change. Personal Policy Existence (270.00) and Policy Limits (50.00) fees are unchanged.
v2.7.0Removed

July 17, 2026

Policy Existence — contact-defendant question retired

The Policy Existence intake question "Can RFR contact the defendant?" has been retired. No integration action is required — you may stop sending the field at your convenience.

  • Removed — can_rfr_contact_defendant: the "Can Red Folder Research contact the defendant?" question has been retired from the Policy Existence intake process. The field is no longer part of the request or response schema for Policy Existence case submission and is no longer required.
  • Compatibility: this is a relaxation — no integration changes are required. Requests that still include can_rfr_contact_defendant continue to succeed (the value is ignored); requests that omit it no longer receive a 400. Responses no longer echo the field.
v2.6.0Changed

July 14, 2026

Testing Guide, Payload Schemas & Validation Reference

A documentation-focused release: how to test your integration, a full field reference for the case payload, every server-side validation check in one place, and the legacy endpoint sunset date. Also includes one small Policy Limit intake-validation fix (see below).

  • Docs — Testing guide published: is_test end-to-end testing is now documented in the API reference, spelling out exactly what a test case does and doesn't trigger. Invoicing of is_test cases is now blocked in code — test cases will never generate a real invoice.
  • Docs — Case payload schemas published: new PartnerCasePolicyLimit / PartnerCasePolicyExistence component schemas document every field of the case JSON with conditional-requirement annotations, and are visible in the Data Dictionary. You no longer need to use the deprecated 3-step endpoints' pages as a field reference.
  • Docs — Validation reference completed: server-side checks beyond the conditional requirements matrix — the date-of-loss window, two-letter state format, nested required members, and carrier escalation rules — are now documented on each endpoint's description, alongside a fully documented error contract (the 400 validation envelope, 401/403 auth failures, and rate limits).
  • Docs — Legacy endpoint sunset date published: the deprecated 3-step endpoints sunset on November 11, 2026. This isn't new behavior — every response from those endpoints has carried the RFC 8594 Sunset header with this date since their deprecation; it's now also published here.
  • Fixed — International commercial parity: international_commercial_policy_limits is now treated as commercial at intake: defendant_business_name is required, and commercial_driver_information is accepted, matching the other three commercial Policy Limit products.
  • Compatibility: the documentation changes above are documentation only — no request/response contract changes for live cases. The international commercial parity fix is a validation tightening: no partner has submitted this product in the past 12 months, and every historical submission of it already included a business name (verified against production 2026-07-14).
v2.5.0Changed

July 13, 2026

Intake validation — USDOT format, unaccepted Policy Limit carriers & MVS advance notice

Commercial Auto Policy Existence submissions now validate that usdot_number is a real USDOT number, not a placeholder. Red Folder Research can only process Commercial Policy Existence requests for transportation companies with an active USDOT number — placeholder values previously reached our research team and were rejected manually. This release also enforces our unaccepted-carrier list on Policy Limit submissions. We are also announcing the Minimum Viable Standard (MVS) for case intake ahead of enforcement.

  • When base_product is commercial_auto_policy_existence, usdot_number must contain digits only with at least one non-zero digit (leading zeros are accepted). Values like "000000" or "N/A" are rejected with 400.
  • Error ordering is unchanged: eligibility errors (is_defendant_transportation_company must be true; usdot_number must be present) still surface before the new format error. See the conditional requirements guide for the full rule matrix.
  • Compatibility: validation tightening on an existing required field. If your integration sends a placeholder USDOT to pass submission, it will now receive a 400 — send the defendant's actual USDOT number, or do not submit non-transportation commercial requests (we cannot process them).
  • insurance_company (and the deprecated insurance_company_name) is rejected with 400 when it names an unaccepted carrier — American National, Federated Insurance, Go Insurance, Security National Insurance, USAA, Wawanesa — including variant spellings (e.g. "AmericanNational Insurance Carrier"). AAA has its own escalation path and is not blocked at submission.
  • Compatibility: tightening on an existing field; carriers on this list were already rejected manually per the published unaccepted-carriers policy.
  • Advance notice — Minimum Viable Standard (MVS): Policy Limit submissions will require the insurance provider, a claim or policy number, and at least one piece of identifying information — an address, date of birth, phone number, VIN, or license plate. Policy Existence submissions will require at least one piece of identifying information. Placeholder values (e.g. "unknown") do not count. Enforcement begins at the start of Q4 2026 (October 1, 2026).
  • Effective immediately, submissions that do not meet MVS are flagged internally to our team. There is no API behavior change until the enforcement date.
v2.4.0Added

July 3, 2026

Partner API — Case Cancellation

You can now request cancellation of a case directly through the API. Cancellation is free before research is dispatched, carries a fee once dispatched, and is unavailable once research is substantially complete. Additive — no breaking changes.

  • New POST /api/v1/partner/cases/{case_ref}/cancel/ — request cancellation of a case. The POST is the consent; there is no confirmation round-trip. Cancellation is free before research is dispatched. Once research has been dispatched, a cancellation fee applies (Policy Limit $50.00 / Policy Existence $270.00). Cancellation is not available once research is substantially complete — in that case the case proceeds to completion.
  • The endpoint returns 202 Accepted: the decision and any fee are returned immediately, and the case closes asynchronously — expect the case.closed webhook to follow. Its reason field carries your cancellation reason verbatim; reason remains free text — do not parse it as an enum. Repeat POSTs are idempotent and replay the original acceptance.
  • Optional request body field reason — free text, up to 2000 characters.
  • New cancellation object on GET /api/v1/partner/cases/{case_ref}/: { "eligible", "fee_usd", "reason" }. reason is one of not_yet_dispatched, dispatched_fee_applies, research_complete, case_closed, cancellation_pending, or case_processing.
  • New 409 error case_processing (retryable): case intake is still completing — retry in a few minutes.
  • For a cancelled fee-tier case, GET /api/v1/partner/cases/{case_ref}/results/ returns a cancelled indicator payload (no fabricated result data) — its status reads cancelled — and the cancellation document is available via the standard results_url download URL.
  • Billing: the cancellation fee, when applicable, is invoiced through our standard billing process. There is no payment surface in the API.
  • Compatibility: Additive. A new endpoint, a new webhook-adjacent async close path, a new object on case detail, and a new 409 error token — no breaking changes. As before, do not configure JSON parsers in strict-unknown-keys mode against the partner contract.
v2.3.0Added

July 1, 2026

Additional Policies in Results JSON + Documentation Overhaul

The partner results JSON now mirrors the PDF for additional policies (upsells), and the docs got a pass across webhooks, getting started, and conditional requirements. Additive — no breaking changes.

  • Added — Additional Policies in Results JSON: the partner results JSON now mirrors the PDF for additional policies (upsells). New always-present additional_policies[] array inside results_data (pre-v2.3.0 results may lack the key until regenerated) with state-aware visibility: offered entries carry only the envelope (type, researcher description, ids, price — values withheld), accepted entries carry the full field set, included entries carry free informational notes. Redaction is by key omission — absent ≠ null. Additive — no breaking changes.
  • Docs — Webhooks: documented all 7 events (added case.files_updated, case.additional_policies_found), delivery/auth/retry mechanics and the HMAC signature header; case.closed reason clarified as free text (not an enum) on non-delivered closes.
  • Docs — Getting started now leads with the one-shot POST /api/v1/partner/cases/create/; the 3-step flow is marked deprecated. Full partner endpoint inventory documented.
  • Docs — Conditional requirements matrix now rendered on the live create endpoint (was: legacy endpoints only).
  • Fixed — Examples: corrected is_defendant_transportation_company (previously showed a stale field name and a payload that now returns 400).
v2.2.0Changed

July 1, 2026

Partner API — Commercial Auto Policy Existence Requires a Transportation Company

Red Folder Research only researches commercial-auto Policy Existence for transportation companies with an active USDOT number. Submission validation now enforces this. Validation tightening — requests that previously passed may now be rejected.

  • On POST /api/v1/partner/cases/create/ with base_product: commercial_auto_policy_existence, is_defendant_transportation_company must now be true. A missing flag or false is rejected with HTTP 400. (Previously the field only had to be present, so false was accepted.)
  • usdot_number remains required whenever is_defendant_transportation_company is true — so a valid commercial-auto Policy Existence request must include both the transportation-company flag and a USDOT number.
  • Compatibility: This is a validation change, not an additive one. Any integration that submitted commercial_auto_policy_existence with is_defendant_transportation_company omitted or false will now receive an HTTP 400. Non-transportation commercial-auto defendants are not eligible for Policy Existence research.
v2.1.0Added

July 1, 2026

Partner API — Additional Policies (Offer & Accept) + Readable Close Reason

When a search turns up additional policies available on a case, you can now be notified and accept them programmatically — a new case.additional_policies_found webhook plus two new endpoints — along with related improvements to results re-delivery and the close reason. Additive — no breaking changes.

  • New case.additional_policies_found webhook — fired when a search turns up additional policies available on a case. The payload includes an offer_id and an additional_policies array; each entry has an upgrade_id, type, researcher_note, price_usd, and status (created = newly offered, selected = already accepted). Add it to your webhook subscription's event list to receive it.
  • New GET /api/v1/partner/cases/{ref}/offers/ — retrieve the current additional-policy offer for a case at any time (idempotent; safe to re-fetch to recover the list).
  • New POST /api/v1/partner/cases/{ref}/offers/accept/ — accept one or more offered policies. Body: { "offer_id": "…", "selected_upgrade_ids": [ … ] }. Idempotent — re-accepting policies you've already accepted returns 200 with the current offer state, never an error.
  • case.results_ready now re-fires when results are regenerated — e.g. after you accept an additional policy, the newly generated results document is delivered as a fresh case.results_ready, so the presigned URL always resolves to the latest PDF.
  • case.closed reject reason is now human-readable — on a rejected/cancelled case, the reason field now carries a free-text explanation (the closing note) when one is available, instead of the generic cancelled. Successful closes are unchanged (results_delivered). Treat reason as a display string, not a fixed enum.
  • Compatibility: Additive. New endpoints, a new webhook event, and a widened reason field — no breaking changes. As before, do not configure JSON parsers in strict-unknown-keys mode against the partner contract.
v2.0.4Added

June 23, 2026

Partner API — case.closed Reason Field + Paid Status Mapping

The case.closed webhook now carries a reason field so you can distinguish a successful delivery from a cancellation. Additive — no breaking changes.

  • case.closed webhooks now include a top-level reason field: results_delivered (the search was completed and the results were delivered — e.g. on full payment, or a close where results were already delivered) or cancelled (the case was closed with no results delivered).
  • The case.closed webhook (with reason: results_delivered) is the authoritative close signal and may precede the read API reporting closed. GET /api/v1/partner/cases/{ref}/ only returns closed once the case reaches the terminal CLOSED status in Jira; in the interim (while in the Paid Jira status), the read API returns results_ready. Treat the webhook as authoritative and do not wait for the read API to reflect closed before acting on this event.
  • The Paid Jira status now maps to results_ready on GET /api/v1/partner/cases/{ref}/ (previously fell through to in_progress).
  • Compatibility: Additive. The new reason field is added without an API version bump — do not configure JSON parsers in strict-unknown-keys mode against the partner contract.
v2.0.3Added

June 2, 2026

Partner API — Result Filename in Webhook + Results Endpoint

The result filename is now returned directly, so you no longer need to parse it out of the presigned S3 URL. Additive — no breaking changes.

  • case.results_ready webhooks now include a file_name field (the result object's filename, e.g. f3a9c2b10d4e_results.pdf) alongside the existing results_url.
  • GET /api/v1/partner/cases/{ref}/results/ (PDF format) now returns the same file_name field next to results_url.
  • Compatibility: Additive. The new field is added without an API version bump — do not configure JSON parsers in strict-unknown-keys mode against the partner contract.
v2.0.2Added

May 28, 2026

Partner API — Webhook message Field + Structured Attachment error_code

Two adjacent quality-of-life improvements based on partner integration feedback. Both additive — no breaking changes.

  • case.action_required webhooks now include a message field with the triggering comment body (capped at 8 KB UTF-8; truncated content ends with …). Pair it with interaction_id when calling the respond endpoint.
  • Attachment rejections on POST /cases/create/ and POST /cases/{ref}/files/ now carry a stable error_code enum: file_too_large, extension_not_allowed, unknown_label, internal_error. Branch on the code instead of string-matching the free-text error. The first three are terminal validation failures (fix the file or label and retry); internal_error is transient — retry once after a short backoff.
  • Compatibility: Both changes are additive. New fields are added without an API version bump — do not configure JSON parsers in strict-unknown-keys mode against the partner contract.
v2.0.1Changed

May 19, 2026

Partner API — Decoupled File Submission

File handling is now decoupled from case creation. File failures no longer abort a submission, and files can be appended to a case in any lifecycle state.

  • POST /api/v1/partner/cases/create/ — the case is always created when the case payload is valid (HTTP 201); file failures are now reported per-file in the attachments array (status: accepted | rejected) and no longer abort the request.
  • POST /api/v1/partner/cases/{ref}/files/ — now a general endpoint for appending a file to a case in any lifecycle state (retry a rejected file or add supplemental material after submission). The 409 response now signals the per-case file/byte cap, not "already submitted".
  • POST /api/v1/partner/cases/{ref}/files/ is idempotent — re-sending identical bytes with the same label returns the existing file record without creating a duplicate.
  • New case.files_updated webhook event fires when a file is appended after case creation. Not fired for idempotent re-uploads.
v2.0.0Added

May 13, 2026

Case Submission v2 — One-Call Multipart

The 3-step declare → upload → submit flow is replaced by a single multipart endpoint. Legacy endpoints continue to work for 6 months (sunset 2026-11-11) and now return the RFC 8594 Deprecation + Sunset response headers.

  • New endpoint POST /api/v1/partner/cases/create/ — send the case JSON and all attachments in one multipart request. Case is created and submitted atomically.
  • New endpoint POST /api/v1/partner/cases/{ref}/files/ — append a file to a draft case (pre-submit). Returns 409 if the case has already been submitted.
  • File labels are now optional metadata per file. The legacy files_to_upload pre-declaration is gone.
  • Canonical labels: incident_report, insurance_letter, driver_license_or_other_id, other (collapsed from other1–other5).
  • Per-request caps: max 10 files, 25 MB per file, 100 MB aggregate.
  • Security: .zip files are no longer accepted (archive bombs / disguised executables risk). Uploaded filenames are sanitized (path traversal, Unicode RTL-override defense).
  • Same authentication. Your Knox token works unchanged.
  • Deprecated: POST /policy_limit_searches/, POST /policy_existence_searches/, POST /upload/{id}/{label}/, PUT /tickets/{id}/ready.
  • See the API reference (sidebar → Partner API) for the full request/response schemas and example payloads.
v1.6.0Added

May 10, 2026

Crash Location Fields (Policy Limit Searches)

Added optional crash_city and crash_state fields to the Policy Limit endpoint, matching the surface added to Policy Existence in v1.5.0.

  • New optional crash_city (free text) field — city where the crash/incident occurred
  • New optional crash_state (two-letter US code) field — automatically expanded to the full state name for Jira
  • Provides location context for researchers, improving search accuracy
  • Both fields default to empty — no changes needed for existing integrations
v1.5.0Added

March 12, 2026

New PE Fields: Defendant Contact & Crash Location

Added a required defendant contact authorization field and optional crash location fields for Policy Existence searches, improving search accuracy and routing.

  • New required boolean field can_rfr_contact_defendant on Policy Existence endpoint
  • Indicates whether RFR may contact the defendant directly as part of the search
  • Smart routing: automatically maps to the correct Jira form field based on personal vs. commercial case type
  • New optional crash_city (free text) and crash_state (two-letter US code) fields
  • State codes are automatically converted to full state names for Jira
  • Existing integrations must update to include can_rfr_contact_defendant; crash location fields are fully optional
v1.4.0Added

March 4, 2026

Test Submissions & Jira Improvements

Introduced the is_test flag for test submissions and improved how plaintiff data and order forms are handled in Jira.

  • New optional boolean field is_test on both PE and PL endpoints — labels Jira cases with TEST for easy filtering
  • Defaults to false — zero impact on existing integrations
  • Plaintiff name now correctly split into separate first and last name fields in Jira
  • Handles all name formats: "First Last", "Last, First", and multi-word names
  • Order forms now automatically set to external (customer-facing) and submitted after population
  • Forms are immediately visible on the Jira portal — no manual intervention needed
v1.3.1Deprecated

February 13, 2026

Deprecation: defendant_name on PE

The defendant_name field on Policy Existence searches is now deprecated. Use the defendant_information object instead for a consistent API across both endpoints.

  • defendant_name is now optional and deprecated on PE — the value is no longer used in downstream processing
  • Canonical source is now defendant_information.first_name and defendant_information.last_name
  • Both PE and PL endpoints now use the same defendant_information object — consistent API surface
  • Field can be omitted entirely — still accepted for backward compatibility but ignored
  • Will be removed in v2.0.0
v1.3.0Added

December 1, 2025

Jira Forms Integration

Tickets created via API now get native Jira Forms automatically attached and populated, replacing the previous PDF form attachment system. Organizations are auto-assigned from your API token.

  • PE and PL forms are automatically created, populated, and submitted — supports both RFR and Black Card projects
  • Organization auto-assignment from your API token — enables org-based features like pricing tiers
  • Smart field mapping: name splitting, commercial vs. personal routing, vehicle info mapping, auto-populated acknowledgment fields
  • New optional text field crash_report_additional_info for additional crash report notes
  • Race condition detection alerts the RFR team if any timing issues occur during form population
  • Fully backward compatible — no changes required to existing integrations
v1.2.2Deprecated

October 21, 2025

Automatic Black Card Detection

The is_black_card field is now automatically determined from your organization's enrollment status. The field is deprecated and its value is ignored.

  • is_black_card now auto-determined from your organization — field is deprecated and values are ignored
  • Fixes a bug where Black Card organization cases were created in the wrong Jira project
  • Detection chain: API token → user account → organization → Black Card enrollment
  • Mismatched values between sent field and detected org status trigger deprecation warnings in logs
  • Affects both PE and PL endpoints — will be removed in v2.0.0
v1.2.1Fixed

October 20, 2025

Malformed Data Handling & Reporter Attribution

Auto-correction for malformed base_product data and improved case reporter attribution using the cc_emails field.

  • Stringified array values like "['commercial_auto_policy_existence']" are now auto-corrected to proper arrays
  • Requests that previously failed with validation errors now process successfully
  • Cases are now attributed to the individual user from cc_emails instead of a generic service account
  • Reporter priority: first email in cc_emails → API token name (if email-like) → service account fallback
  • Coordinators receive notification if a user email doesn't match any Jira account
v1.2.0Changed

October 20, 2025

base_product Field Consistency

The Policy Existence endpoint now accepts both string and array format for base_product, bringing consistency with Policy Limits. Array format is recommended.

  • PE endpoint now accepts both string and array format for base_product
  • Array format is now the recommended approach for both PE and PL endpoints
  • String format remains supported on PE but is deprecated — will be removed in v2.0.0
  • No breaking changes — existing integrations continue to work without modification
  • Deprecation warnings logged when string format is used, guiding migration
v1.1.0Changed

October 19, 2025

Insurance Company Simplification & Nullable DOB

Simplified the insurance company field on Policy Limits to accept both predefined and custom names in a single field, and made date_of_birth nullable.

  • insurance_company field now accepts both predefined names and custom company names directly
  • Case-insensitive matching for known companies (e.g., "Farmers", "FARMERS", "farmers" all work)
  • insurance_company_name field deprecated — use the single insurance_company field instead
  • date_of_birth in defendant_information now accepts null, empty string, or can be omitted entirely
  • All changes are backward compatible — deprecation warnings logged for old field usage
v1.0.0Added

Initial Release

Initial API Release

The first public release of the RedFolderResearch Ticketing API, providing core search submission and file upload capabilities.

  • Policy Existence Search endpoints for personal auto, commercial auto, and homeowners
  • Policy Limit Search endpoints for personal auto, commercial auto, CGL, homeowners/renters, and more
  • Token-based authentication system with master token / user token exchange
  • File upload capabilities for supporting documents via multipart form data