/v2/riskBetaSubmit 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.
https://api.relativity6.comAuthentication
Send your API key in the x-api-key header. Send your API key in this header on every request. Production keys use r6-<keyId>.<secret>. Test keys use r6-test-<keyId>.<secret>. See Environments.
Request headers
Idempotency-KeyOptional. Retries with the same key reuse the original job and do not charge credits again.
X-R6-FixtureOptional. Test keys only. Set to default to queue a canned job that completes without consuming credits. Poll the returned poll_url as usual. Production keys receive HTTP 400 (FIXTURE_TEST_KEY_REQUIRED). See Environments.
Request body
| Field | Type | Required | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| company_name | string | Required | Legal or trade name of the business (2–200 characters). | ||||||||||||||||
| website | string | Optional | Primary website domain (for example, acmerobotics.com). Improves match accuracy. | ||||||||||||||||
| address | string | Optional | Street address. | ||||||||||||||||
| city | string | Optional | City. | ||||||||||||||||
| state | string | Recommended | State or region code. Strongly recommended to disambiguate the entity. | ||||||||||||||||
| zip | string | Optional | Postal or ZIP code. | ||||||||||||||||
| country | string | Optional | Two-letter country code (for example, US). | ||||||||||||||||
| policy_id | string | Optional | Your own reference id, echoed back and stored with the result for reconciliation. | ||||||||||||||||
| enabled_categories | string[] | Optional | Optional Core+ category ids to run in addition to Core. Omit or pass [] for a Core-only job. Core ids in this list are ignored. Do not send coming-soon ids (liquor_licenses, ofac_restricted_lists, trade_licenses). Sending plan, addons, or entitlements returns 400. See Core & Core+. | ||||||||||||||||
| naics_year | string | Optional | NAICS vintage for industry classification. Default is 2017 unless 2022 is sent.2017 · 2022 | ||||||||||||||||
| classify | object | Optional | Industry classification options for Core industry_classification. See Core & Core+. | ||||||||||||||||
| |||||||||||||||||||
| business_risk_flags | object | Optional | Filters and profile selection for Core+ business_risk_flags. See Core & Core+. | ||||||||||||||||
| |||||||||||||||||||
| osha | object | Optional | Options for Core+ OSHA. See Core & Core+. | ||||||||||||||||
| |||||||||||||||||||
| cache | object | Optional | Request cache control. | ||||||||||||||||
| |||||||||||||||||||
Response
| Field | Type | Required | Description |
|---|---|---|---|
| job_id | string | Required | Unique id for this job. Use it to poll status and to match webhook deliveries. |
| status | string | Required | Lifecycle state. Always queued on the initial response.queued · running · completed · failed |
| company_name | string | Optional | Company name echoed from the request. |
| poll_url | string | Required | Relative path to poll for status and the final result (GET /v2/risk/{job_id}). |
| created_at | string (ISO 8601) | Optional | When the job was accepted. |
Response headers
LocationPath to the job status endpoint for this job (GET /v2/risk/{job_id}).
RateLimit-PolicyStructured policy descriptor reporting your sustained per-minute quota (q, w=60) and per-second burst capacity (w=1) for this endpoint group.
RateLimitRemaining requests (r) in the current sustained window and seconds until reset (t).
Retry-AfterReturned on HTTP 429 responses. Whole seconds to wait before retrying.
Errors
| Status | Description |
|---|---|
| 202 | Accepted. The job was queued; poll the returned poll_url for results. |
| 400 | Invalid request body (for example, missing company_name, or a removed plan / addons / entitlements field), or X-R6-Fixture sent with a production key. |
| 401 | Missing or invalid API key. |
| 402 | Insufficient credits. Body includes code INSUFFICIENT_CREDITS, credits_needed, and remaining_credits. |
| 403 | Organization is not authorized for Risk API v2 (for example, a v1 account, expired trial, or suspended org). |
| 429 | Rate limit or active job concurrency limit exceeded (codes RATE_LIMIT_EXCEEDED or MAX_CONCURRENT_JOBS_EXCEEDED). No credits are charged — wait Retry-After seconds and retry. |
| 500 | Server error. Credits charged for a job that never started are refunded. |