Relativity6Platform Docs
POST/v2/riskBeta

Submit a risk job

Starts an asynchronous risk assessment for a company and returns immediately with a job you can poll. Research runs in the background and can take a few minutes; you never hold a long-lived connection. Use the returned poll_url to check progress and retrieve the final result, or register a webhook to be notified on completion.

Beta. This endpoint is available for production integrations, but fields, categories, and credit weights may change without a version pin.

Base URLhttps://api.relativity6.com

Authentication

Send your API key in the x-api-key header. Send your API key in this header on every request. Modern keys use the format r6-<keyId>.<secret>.

Request headers

  • Idempotency-Key

    Optional. Retries with the same key reuse the original job and do not charge credits again.

Request body

FieldTypeRequiredDescription
company_namestringRequiredLegal or trade name of the business (2–200 characters).
websitestringOptionalPrimary website domain (for example, acmerobotics.com). Improves match accuracy.
addressstringOptionalStreet address.
citystringOptionalCity.
statestringRecommendedState or region code. Strongly recommended to disambiguate the entity.
zipstringOptionalPostal or ZIP code.
countrystringOptionalTwo-letter country code (for example, US).
policy_idstringOptionalYour own reference id, echoed back and stored with the result for reconciliation.
planstringOne of plan, entitlements, or addonsNamed bundle that determines which categories run — for example "core". Every request must state what to run. Omitting plan, entitlements, and addons returns 400. See Categories & access.core · core_plus_government · core_plus_risk · core_plus_property · core_plus_compliance_lists
entitlementsstring[]One of plan, entitlements, or addonsFine-grained capability ids to run. Use instead of plan for precise control. A request with none of plan, entitlements, or addons returns 400. The resolution backbone and summary are always included.
addonsstring[]One of plan, entitlements, or addonsAdditional named bundles layered on top of plan. addons alone is a valid selection.
enabled_categoriesstring[]OptionalDeprecated. Legacy category id list — prefer entitlements, plan, or addons. Categories not on your account are skipped.
naics_yearstringOptionalNAICS vintage for industry classification (for example, 2022).2017 · 2022
classifyobjectOptionalIndustry classification options.
familiesstring[]OptionalCode families to return (for example, naics, sic).
naics_yearstringOptionalNAICS vintage when classify is set.2017 · 2022
business_risk_flagsobjectOptionalFilters and profile selection for the business risk flags category.
category_filterstring[]OptionalLimit evaluation to specific flag categories.
flag_filterstring[]OptionalLimit evaluation to specific flag names.
profile_sourcestringOptionalWhich risk profile drives flag evaluation when profile_id is omitted. default uses the Business Risk Flags package; org uses the organization's active default.default · org
profile_idstringOptionalOptional portfolio override. UUID of an org-owned profile or a global package the organization has installed. Takes precedence over profile_source. Returns 400 if the profile is not available to the organization.
oshaobjectOptionalOptions for the OSHA public-records category.
layernumberOptionalInspection depth tier (1, 2, or 3).1 · 2 · 3
cacheobjectOptionalRequest cache control.
modestringOptionaldefault uses the cache; ignore bypasses it for this request.default · ignore

Response

FieldTypeRequiredDescription
job_idstringRequiredUnique id for this job. Use it to poll status and to match webhook deliveries.
statusstringRequiredLifecycle state. Always queued on the initial response.queued · running · completed · failed
company_namestringOptionalCompany name echoed from the request.
poll_urlstringRequiredRelative path to poll for status and the final result (GET /v2/risk/{job_id}).
created_atstring (ISO 8601)OptionalWhen the job was accepted.

Response headers

  • Location

    Path to the job status endpoint for this job (GET /v2/risk/{job_id}).

Errors

StatusDescription
202Accepted. The job was queued; poll the returned poll_url for results.
400Invalid request body (for example, missing company_name or no plan/entitlements/addons).
401Missing or invalid API key.
402Insufficient credits. Body includes code INSUFFICIENT_CREDITS, credits_needed, and remaining_credits.
403Organization is not authorized for Risk API v2 (for example, a v1 account, expired trial, or suspended org).
500Server error. Credits charged for a job that never started are refunded.

Example request

Example response