---
title: "Request AI-suggested corrections for failed rows"
method: POST
path: "/roster-records/{rosterId}/smartfix"
tags: ["RosterRecord"]
---

# Request AI-suggested corrections for failed rows

`POST /roster-records/{rosterId}/smartfix`

Sends the roster's validation failures to an AI correction service and returns suggested values for the cells it can repair.

**When to use:** call this once validation has run and rows are sitting in `VALIDATION_FAILED` state. Saving drafts first is not required - Smart Fix reads the failed rows directly. Review what comes back, then apply the suggestions you accept with `PATCH /roster-records/{rosterId}/draft` and re-run validation.

**Preconditions:** supply the `tenant-id` header and the `rosterId` of an existing roster job. The roster must hold at least one `VALIDATION_FAILED` row carrying an error type eligible for correction - incorrect data type, invalid date, email, or format, a value outside the allowed set, an invalid NPI, or a missing required field. Rosters with more than 2000 failed rows are rejected with 400; resolve some rows and call again. Whether practitioner or facility rules are applied is derived from the roster's own job type and is not a caller-supplied parameter.

**Cost:** the failures are sent to the correction service in batches, so this call takes noticeably longer than a typical request on a large roster.

**What you get back:** one suggestion per correctable cell, each naming the source column, the original value, the system attribute it maps to, the suggested replacement, a confidence rating, and a status of `auto_fixed`, `llm_suggested`, or `requires_human_review`. Every suggestion carries the `rowIndex`, which is the row's `rowId`, so it can be matched back to the row it came from. The response also reports how many errors were submitted, fixed, and skipped, whether every batch succeeded, and any batch-level error messages. **No rows are modified by this call** - it reads and suggests, and nothing is stored until you save drafts. Calling it again on the same rows simply returns a fresh set of suggestions. Smart Fix can be turned off for the platform, in which case this endpoint returns 503 until it is re-enabled.

## Path parameters

- `rosterId` string, required

## Headers

- `tenant-id` string, required

## Response `200`

Suggested corrections for the roster's failed cells, with per-suggestion confidence and the totals for the run. No roster data has been changed.

- SmartFixTriggerResponse — Aggregated Smart Fix response returned to the frontend
  - `suggestions` EnrichedSuggestion[] — Per-error fix suggestions enriched with rowId
    - `fieldName` string — CSV column header
    - `currentValue` string — Original cell value
    - `mappedAttribute` string — System attribute name (e.g. dateOfBirth)
    - `errorCategory` string — Error category sent to Smart Fix
    - `suggestedValue` string — Corrected value, or null if unfixable
    - `confidence` string — high, medium, or low
    - `confidenceScore` number, double — Numeric confidence 0.0-1.0
    - `reasoning` string — Explanation of the correction
    - `status` string — auto_fixed, llm_suggested, or requires_human_review
    - `rowIndex` string — Spanner row_id (recordKey) for correlating back to RosterRowItem
  - `totalErrors` integer — Total validation errors sent to Smart Fix
  - `totalFixed` integer — Errors for which a suggested_value was returned
  - `totalSkipped` integer — Errors where no fix could be suggested
  - `totalRowsProcessed` integer — Number of VALIDATION_FAILED rows processed
  - `success` boolean — True if all Smart Fix batches succeeded
  - `batchErrors` string[] — Error messages from any failed batches

## Other responses

- `400` — Returned when the roster holds more failed rows than Smart Fix accepts, or none of its failures are of a correctable type. Reduce the number of failed rows, or fix the remaining errors manually.
- `401` — Returned when the request carries no valid authentication.
- `403` — Returned when the caller lacks the UPDATE_ROSTER permission for this tenant.
- `404` — Returned when no roster job with the supplied `rosterId` exists for the tenant.
- `503` — Returned when Smart Fix is currently turned off for the platform. This is a temporary operational state - contact support if it persists.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)