# score (/reference/score)



See [Scores](/concepts/scores).

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

Scores one record with a score you [created](/reference/create-score): an integer from 0 (lowest risk) to 1000 (highest), about the probability of a bad outcome times 1,000. The record must have the fields of the score's [schema](/concepts/scores#schema).

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's id, from [Create a score](/reference/create-score). |
| `score_id` | string | yes | Your id for this record, unique within the score. Send it back with the outcome to [calibrate](/reference/calibrate). |
| `data` | object or array of object or string | yes | One record, with the fields of the score's examples. A JSON object (or an array holding one), or CSV text with a header and one row. Up to 60,000 bytes as compact JSON. An `is_bad` field is ignored. |
| `skip_schema_validation` | boolean |  | Score the record even if its fields differ from the score's [schema](/concepts/scores#schema). |
| `update_schema` | boolean |  | Score it and make its fields the schema from now on. |

Example:

```json
{
  "model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9",
  "score_id": "pay_88213",
  "data": {
    "amount_usd": 1850,
    "merchant_category": "electronics",
    "account_age_days": 6,
    "new_device": true,
    "billing_country": "US",
    "ip_country": "RO"
  }
}
```

### Responses

- **200**: The score.

| Field | Type | Always | Description |
| --- | --- | --- | --- |
| `model_id` | string | yes | The score's id |
| `score_id` | string | yes | As sent. |
| `score` | integer | yes | 0 (lowest risk) to 1000 (highest); score ÷ 1000 is about the probability of a bad outcome. |
| `request_id` | string | yes | `req_…`, the same as the `X-Request-Id` header. |

```json
{
  "model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9",
  "score_id": "pay_88213",
  "score": 874,
  "request_id": "req_01M4YF1068X8B4C458ENPD4JHT"
}
```

- **400**: - `invalid_request`: `model_id` or `score_id` is missing, `score_id` is over 200 characters, or `data` isn't one record.
  - `schema_mismatch`: the record's fields differ from the score's schema. The message lists them.

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

- **402**: `insufficient_credit`: the organization is out of credit. An admin adds more in the Finic Portal.

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

- **409**: - `score_not_ready`: the score is still being created (check its job), or creating it failed (create it again).
  - `duplicate_score_id`: this score already has this `score_id`. A retry of a call that timed out but succeeded gets this, without the first call's score.

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

- **429**: `rate_limited`: over the organization's [request rate](/reference#rate-limits). Retry with backoff.

- **503**: `overloaded`: temporarily at capacity. Retry with backoff.