# Create an adverse action

Finalizes an adverse decision against the subject identified by `check_id`.
Use this when your organization is declining a subject based in whole or in part
on the results of a Checkr background check.
Delivers the required adverse action notice to the subject so they can seek
assistance or initiate a dispute. In the event a dispute is resolved with changes
to the report, Checkr will notify your organization so you can reassess
the subject's eligibility.
May be submitted with or without a prior pre-adverse action.
Including `disqualifying_records` is optional but strongly recommended — FCRA
requires disclosing which records triggered the adverse decision.

Endpoint: POST /regulated/adverse_actions
Version: 1.0
Security: get-bearer-token-using-oauth2

## Security:

  - `get-bearer-token-using-oauth2` (unknown)
    oauth2

## Request fields (application/json):

  - `check_id` (string, required)
    A universally unique identifier (UUID) in standard format.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `email` (string, required)
    An email address.
    Example: john.doe@example.com

  - `suppress_notice` (boolean)
    When `true`, the notice email is not sent to the subject. The `candidate_report_url`
is still populated in the response. Defaults to `false`.

  - `disqualifying_records` (array)
    The criminal records that triggered the adverse decision. Optional but recommended.

  - `disqualifying_records.record_id` (string, required)
    The ID of the criminal record within a check result.
    Example: record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e

## Response 201:

  - `201` (unknown)
    Created

## Response 201 fields (application/json):

  - `id` (string)
    A universally unique identifier (UUID) in standard format.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `status` (string)
    The status associated with the adverse action.
    Example: AdverseActionInitiated

  - `candidate_report_url` (string | null)
    Subject-facing URL for viewing the background check report and responding to the notice.
When a subject UI is configured this is a deep link keyed by the adverse action id,
gated by a one-time code sent to the subject's email so the customer cannot open it
directly; you may still share it with the subject, and Checkr emails it to them unless
`suppress_notice` is set. Where no subject UI is configured, this is a support `mailto:`
link instead (no OTP gating).
    Example: https://subjects.checkrtrust.com/2b8313e8-4efd-45a1-b578-952b8313e890/review

  - `disqualifying_records` (array)

  - `disqualifying_records.record_id` (string, required)
    The ID of the criminal record within a check result.
    Example: record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e

  - `created_at` (string)
    An ISO 8601 formatted date-time string.
    Example: 2020-01-01T00:00:00Z

  - `sent_at` (string | null)
    Timestamp when the notice was delivered. Null until status is `sent`.
    Example: 2024-06-01T14:00:00Z

## Response 400:

  - `400` (unknown)
    Validation error. One of:
- `check_id` is missing, `email` is missing, or the regulated check does not exist for this account.
- Adverse action is not enabled for the product configuration of this check.
- The regulated check is more than 1 year old and cannot be used as the basis for an adverse action; run a new regulated check first.
- An adverse action for this `email` was already initiated on this account within the last 30 days. Wait for the window to expire or use a different email.
- The profile's first/last name is too common to act on without a middle name. Add a `middle_name` to the profile, or set `no_middle_name: true` to confirm there is no middle name.
- The check has no criminal records to start an adverse action against.
- One or more `disqualifying_records[].record_id` values do not appear on the check's records.

## Response 400 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 401:

  - `401` (unknown)
    Error response

## Response 401 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 403:

  - `403` (unknown)
    Error response

## Response 403 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 409:

  - `409` (unknown)
    Conflict — one of:
- an adverse action has already been initiated for this check;
- the candidate already has a standing adverse action on file (a non-reversed final adverse action, or an active dispute, on any of their checks), which locks the profile; or
- another of the candidate's checks already has an adverse-action cycle in progress (only one cycle per candidate at a time).

## Response 409 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 500:

  - `500` (unknown)
    Error response

## Response 500 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Callback:

  - `onAdverseActionDisputeFiled` (unknown)
    Adverse Action Dispute Filed Webhook Callback (webhook) triggered when a subject files a dispute against a (pre-)adverse
action. Fires for both pre-adverse and final-adverse disputes — inspect
`data.adverse_action_type` to tell them apart.
Configure the destination URL (and optionally a signing key) via the
`adverse_action_webhooks` settings on the account's adverse-action-enabled
product configuration (`instant_criminal_regulated` or `county_criminal_regulated`) — the same destination used for pre-adverse-action webhooks.
Refer to the main [Webhooks](./index.md#webhooks) documentation for details on
signature verification.

  - `onAdverseActionDisputeResolved` (unknown)
    Adverse Action Dispute Resolved Webhook Callback (webhook) triggered when an admin resolves a filed dispute, either with
changes to the report (`DisputeResolvedWithChanges`) or without
(`DisputeResolvedWithoutChanges`). Fires for both pre-adverse and final-adverse
disputes — inspect `data.adverse_action_type` to tell them apart.
Configure the destination URL (and optionally a signing key) via the
`adverse_action_webhooks` settings on the account's adverse-action-enabled
product configuration (`instant_criminal_regulated` or `county_criminal_regulated`).
Refer to the main [Webhooks](./index.md#webhooks) documentation for details on
signature verification.

## Callback request body:

  - `application/json` (unknown)
    Minimal payload identifying the dispute, its parent (pre-)adverse action, and
type. Fetch full details (including dispute timestamps) via
`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}` or
`GET /v1/regulated/adverse_actions/{adverse_action_id}`, selected by
`data.adverse_action_type`.

  - `application/json` (unknown)
    Minimal payload identifying the dispute, its parent (pre-)adverse action, and
resolution outcome. Fetch full details (including dispute timestamps) via
`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}` or
`GET /v1/regulated/adverse_actions/{adverse_action_id}`, selected by
`data.adverse_action_type`.

## Callback request fields (application/json):

  - `id` (string, required)
    A universally unique identifier (UUID) in standard format.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `object` (string, required)
    Enum: "event"

  - `type` (string, required)
    Enum: "adverse_action.dispute_filed"

  - `created_at` (string, required)
    An ISO 8601 formatted date-time string.
    Example: 2020-01-01T00:00:00Z

  - `data` (object, required)

  - `data.adverse_action_type` (string, required)
    Which lifecycle stage the dispute belongs to, and which GET endpoint to call.
`pre_adverse_action` — dispute against a pre-adverse action notice
(`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}`).
`adverse_action` — dispute against a final adverse action
(`GET /v1/regulated/adverse_actions/{adverse_action_id}`).
    Enum: "pre_adverse_action", "adverse_action"

  - `data.status` (string, required)
    Status of the adverse action after the dispute was filed.
    Enum: "DisputeFiled"

  - `id` (string, required)
    A universally unique identifier (UUID) in standard format.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `object` (string, required)
    Enum: "event"

  - `type` (string, required)
    Enum: "adverse_action.dispute_resolved"

  - `created_at` (string, required)
    An ISO 8601 formatted date-time string.
    Example: 2020-01-01T00:00:00Z

  - `data` (object, required)

  - `data.adverse_action_type` (string, required)
    Which lifecycle stage the dispute belongs to, and which GET endpoint to call.
`pre_adverse_action` — dispute against a pre-adverse action notice
(`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}`).
`adverse_action` — dispute against a final adverse action
(`GET /v1/regulated/adverse_actions/{adverse_action_id}`).
    Enum: "pre_adverse_action", "adverse_action"

  - `data.status` (string, required)
    Resolution outcome.
`DisputeResolvedWithChanges` — the report was adjusted; reassess the subject's eligibility.
`DisputeResolvedWithoutChanges` — the report stands as-is.
    Enum: "DisputeResolvedWithChanges", "DisputeResolvedWithoutChanges"

## Callback response 2xx:

  - `2xx` (unknown)
    Return any 2xx status to acknowledge receipt. We treat any 2xx as success and
will not retry the POST.

  - `2xx` (unknown)
    Return any 2xx status to acknowledge receipt. We treat any 2xx as success and
will not retry the POST.

## Callback response 4xx:

  - `4xx` (unknown)
    4xx responses are treated as client errors and may trigger retries depending on
the specific status code.

  - `4xx` (unknown)
    4xx responses are treated as client errors and may trigger retries depending on
the specific status code.

## Callback response 5xx:

  - `5xx` (unknown)
    5xx responses are treated as server errors and will be retried automatically.

  - `5xx` (unknown)
    5xx responses are treated as server errors and will be retried automatically.