# calibrate (/reference/calibrate)



Up to 10 calibrations per score per day. See [Calibration](/concepts/calibration#calibrate-a-score).

## POST https://api.finic.ai/v1/calibrate

Sends the outcomes of records you [scored](/reference/score), matched by `score_id`, and updates the score with them. Returns `202` with a `job_id`; score calls after the [job](/reference/get-job-status) completes use the updated score. One calibration at a time per score. Rows whose `score_id` wasn't sent to this score are skipped; sending an outcome again replaces it. A failed request records none of its outcomes.

Authorization: `Bearer <API key>` (see [Authentication](/authentication)).

### Request body (application/json or multipart/form-data)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model_id` | string | yes | The score these outcomes are for. |
| `data` | array of object or string | yes | The outcomes: a JSON array of rows, or CSV text with a header row. A `model_id` in a row must match; other row fields are ignored. |

Example:

```json
{
  "model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9",
  "data": [
    {
      "score_id": "pay_88213",
      "is_bad": true
    },
    {
      "score_id": "pay_88214",
      "is_bad": false
    }
  ]
}
```

### Responses

- **202**: The calibration is running.

| Field | Type | Always | Description |
| --- | --- | --- | --- |
| `job_id` | string | yes | The calibration's job, `job_…`. |
| `matched` | integer | yes | Rows that matched a call to this score. |
| `unmatched` | integer | yes | Rows skipped. |
| `request_id` | string | yes | `req_…`, the same as the `X-Request-Id` header. |

```json
{
  "job_id": "job_01M4YY4AZRJ8NR5QFRW628CJ5G",
  "matched": 2,
  "unmatched": 0,
  "request_id": "req_01M4YPJNK0SZGEQS0A76EEND4N"
}
```

- **400**: `invalid_request`: `model_id` is missing, a row breaks a rule, or no `score_id` matches a call to this score.

- **401**: `authentication_error`: the API key is missing, unknown, revoked or expired.

- **404**: `score_not_found`: no score with this `model_id` in your organization.

- **409**: - `score_not_ready`: the score is still being created, or creating it failed.
  - `calibration_in_progress`: a calibration is already running. Send these again when its job completes.

- **413**: `request_too_large`: over 2 MB, or the record is too large.

- **429**: `rate_limited`: 10 calibrations of this score in the last 24 hours, or over the [request rate](/reference#rate-limits).