Classification

Send at least a company name. Adding city, state, or a full address usually improves match quality. Each successful call consumes one Marvin2 API quota unit.

Successful responses include the X-Marvin2-Cache header (HIT or MISS). See Caching for how caching works. Use accuracy on each prediction for automation thresholds — see Confidence scores.

For the complete field list and error codes, see the classification API reference.

Predictions are grouped under a key that depends on predictionType. For NAICS 2022, look at usa_naics_2022_prediction_hp:

• prediction_a — primary classification
• prediction_b — alternate classification (when you request two predictions)

Each prediction includes code, title, and accuracy (from 0.10 to 0.95).

Optional top-level fields (when enabled in responseConfig) include keywords, company_website, existence_check, and business_description. The response also includes responseId and timestamp for logging and support.

Balanced mode researches the business on the web before classifying. Fast mode returns sooner with less research.

If you already have a reliable business description and do not need web research, use description-only mode below.

Set predictionType on your request. If you omit it, the API defaults to USA_NAICS_2017.

Predictions always use the same shape inside the type-specific object:

{
  "prediction_a": { "code": "...", "title": "...", "accuracy": 0.85 },
  "prediction_b": { "code": "...", "title": "...", "accuracy": 0.72 }
}

(prediction_b is omitted when responseConfig.numberOfPredictions is 1.)

NAICS codes

Each prediction includes a 6-digit code and the official NAICS title for that vintage. Pick the vintage that matches your policy forms, filings, or downstream data warehouse.

SIC codes

Each prediction includes a 4-digit code and the official SIC title. Codes are validated against the Relativity6 SIC registry (same guarantee pattern as NAICS: retries, then a static fallback if needed).

Workers comp and general liability

Choosing a type

• One request, one type — Send separate API calls if you need both NAICS 2022 and workers comp codes for the same company.
• Stable parsing — The response key tells you which code system you received.
• Same tuning fields — responseConfig, searchMode, and descriptionOnly apply to every predictionType.

Add a responseConfig object to your request. All fields are optional; when you omit responseConfig, the API uses these defaults:

Number of predictions

numberOfPredictions accepts 1 or 2.

• 2 (default) — returns prediction_a and prediction_b. Use when you want a primary and alternate code.
• 1 — returns only prediction_a. Use when you only need a single best match.

Optional response fields

Set any of these to false to omit that data from the response.

Latency and cost tips

For high-volume or latency-sensitive workflows, combine a lean responseConfig with searchMode: "fast":

Set descriptionOnly to true to skip web search and classify using only request fields plus your description text.

What it does

The service still returns the same prediction structure (for example usa_naics_2022_prediction_hp.prediction_a) and honors responseConfig. searchMode has no effect — web research is not performed.

Requirements

Example request

Provide enough detail for a human underwriter to pick an industry code — products, customers, operations, and what the business does not do.

When to use it

Good fits: you already have a detailed description in your application or CRM; testing with fixed inputs; environments where outbound web research is undesirable.

Prefer standard mode (descriptionOnly: false, default) when you want the service to discover websites, keywords, and existence evidence from the open web.

Limitations

• Optional fields tied to web research are usually empty or less useful — turn them off in responseConfig.
• Description-only does not bypass cache; identical bodies still return X-Marvin2-Cache: HIT.