Claim Complexity Input Options

Status: beta Category: claimcomplexity Added: 2026-08-07 Last reviewed: 2026-08-07

Summary

Return the accepted values for every POST /api/claimcomplexity/predict feature: the numeric range for each numeric field, the accepted gender codes, the accepted industry_title strings, and the definition of the outcome the model was trained to predict.

Call this first. Validating against this response costs 1 credit and avoids paying full price for a predict call that would only return 400.

Endpoint

Field	Value
Method	GET
Path	/api/claimcomplexity/options
Full URL	https://engine.tripod-health.com/api/claimcomplexity/options
Authentication	API key (required)
Request body	none
Response body	application/json
Idempotent	Yes
Rate-limited	Yes

Purpose

The industry_title vocabulary is fixed, exact-match, and long enough that guessing at it reliably fails. This endpoint is the source of truth for it, and for the numeric bounds the request validator enforces.

It also publishes target_definition — the rule that labelled a historical claim "high complexity" in the training data. Read it before you act on a prediction: it tells you what the model actually learned, which is narrower than the everyday meaning of "complex."

Authentication

Send a valid API key in the apikey header. A missing or unknown key returns 401 Unauthenticated at the gateway before the request reaches the engine. See authentication.

Request

Headers

Header	Required	Description
apikey	Yes	Consumer API key.

Path parameters

None.

Query parameters

None.

Body

None — GET endpoint.

Response

Success — 200 OK

{
  "age_at_injury": { "minimum": 0, "maximum": 120 },
  "average_weekly_wage": { "minimum": 0, "maximum": 10000000 },
  "birth_year": { "minimum": 1900, "maximum": 2100 },
  "accident_month": { "minimum": 1, "maximum": 12 },
  "genders": ["F", "M", "U", "X"],
  "industries": [
    "Accommodation and Food Services",
    "Administrative and Support and Waste Management and Remediation Services",
    "Agriculture, Forestry, Fishing and Hunting",
    "Arts, Entertainment, and Recreation",
    "Construction",
    "Educational Services",
    "Finance and Insurance",
    "Health Care and Social Assistance",
    "Information",
    "Management of Companies and Enterprises",
    "Manufacturing",
    "Mining, Quarrying, and Oil and Gas Extraction",
    "Other Services (except Public Administration)",
    "Professional, Scientific, and Technical Services",
    "Public Administration",
    "Real Estate and Rental and Leasing",
    "Retail Trade",
    "Transportation and Warehousing",
    "Unknown",
    "Utilities",
    "Wholesale Trade"
  ],
  "target_definition": {
    "hearing_count_threshold": 1,
    "ime4_count_threshold": 4,
    "alternative_dispute_resolution": "Yes"
  }
}

Response fields

Field	Type	Always present	Description
age_at_injury	object	Yes	Inclusive minimum / maximum accepted for the age_at_injury feature.
average_weekly_wage	object	Yes	Inclusive minimum / maximum accepted for average_weekly_wage, in whole US dollars.
birth_year	object	Yes	Inclusive minimum / maximum accepted for birth_year, as a four-digit year.
accident_month	object	Yes	Inclusive minimum / maximum accepted for accident_month, as a month number.
genders	array<string>	Yes	Accepted gender codes. Exact match, case-sensitive.
industries	array<string>	Yes	Accepted industry_title values. Exact match on the full string.
target_definition	object	Yes	The rule that labelled a training claim high-complexity. See below.

target_definition

A historical claim was labelled high-complexity when any of these held:

Field	Meaning
hearing_count_threshold	A claim with at least this many hearings qualified.
ime4_count_threshold	A claim with at least this many IME-4 independent medical exam forms qualified.
alternative_dispute_resolution	A claim carrying this ADR flag value qualified.

These are procedural markers from the New York Workers' Compensation Board research dataset. They are a proxy for a claim becoming administratively involved — not a measure of injury severity, medical difficulty, or cost. The values may change when the model is retrained; read them from this endpoint rather than hardcoding them.

The minimum / maximum bounds are the request validator's accepted range, not the range the model was trained on. A value inside the range is accepted; a value far outside the training distribution is still accepted and still returns a prediction, but with correspondingly little to base it on.

Status codes

Code	Meaning	When
200	OK	Options returned.
401	Unauthenticated	Missing or invalid API key.
402	PaymentRequired	Insufficient credits or an exhausted budget. See credits.md.
429	RateLimited	Per-consumer rate limit exceeded. See Retry-After.
500	InternalError	Unexpected server-side failure. Include request_id when reporting.
502	UpstreamError	The model service was unreachable or returned an unexpected shape.
503	ServiceUnavailable	A required dependency is temporarily unhealthy.
504	UpstreamTimeout	The model call exceeded the engine's budget.

Error envelope

All non-2xx responses use the uniform envelope. See errors.md.

What a call costs

1 credit — the discovery floor. This route is priced so that validating inputs is always cheaper than a rejected predict. The exact credits spent are in the X-Credits-Used header and the dollar cost in X-Credits-Cost-USD. See credits.md.

The response is stable between model releases. Cache it rather than calling it before every prediction.

Examples

curl

curl -sS "https://engine.tripod-health.com/api/claimcomplexity/options" \
  -H "apikey: $ENGINE_API_KEY"

Python (requests)

# Uses the call() helper from quickstart.md.
options = call("GET", "/api/claimcomplexity/options")

industries = set(options["industries"])
if my_industry not in industries:
    raise ValueError(f"{my_industry!r} is not an accepted industry_title")

Node.js (native fetch)

// Uses the call() helper from quickstart.md.
const options = await call("GET", "/api/claimcomplexity/options");

const industries = new Set(options.industries);
if (!industries.has(myIndustry)) {
  throw new Error(`${myIndustry} is not an accepted industry_title`);
}

TypeScript

interface NumericRange {
  minimum: number;
  maximum: number;
}

interface ClaimComplexityOptionsResponse {
  age_at_injury: NumericRange;
  average_weekly_wage: NumericRange;
  birth_year: NumericRange;
  accident_month: NumericRange;
  genders: string[];
  industries: string[];
  target_definition: {
    hearing_count_threshold: number;
    ime4_count_threshold: number;
    alternative_dispute_resolution: string;
  };
}

const options = await call<ClaimComplexityOptionsResponse>(
  "GET",
  "/api/claimcomplexity/options",
);

Intended use

• Populate a dropdown for industry_title and gender from the live list rather than a copy that silently goes stale.
• Pre-validate a batch before spending 150 credits per row on predict.
• Read target_definition so your interpretation of a prediction matches what the model was trained to detect.

Mistaken use

• Do not hardcode the industries array. It is versioned with the model and will change on retrain. Fetch and cache it.
• Do not call this before every prediction. The values change on the order of model releases, not requests.
• Do not read the numeric bounds as the training range. They are the validator's accepted range; the two are not the same.

Rate limits

Per-consumer limits apply; see rate-limits.md. Responses include the standard RateLimit-* headers.

Related

• claimcomplexity-predict.md — the prediction call these options feed.
• claimcost-classify.md — a separate model that estimates claim cost category rather than procedural complexity.
• credits.md — the credit model and the X-Credits-* headers.
• errors.md — error envelope and code list.

Change history

Date	Change
2026-08-07	Initial publication (beta).
2026-10-14	The engine assigns every request ID; an X-Request-ID request header is not used.