# create_scoring_model (/reference/create-scoring-model)



Up to 100 new scoring models per organization per day. Created from labeled examples, a scoring model is calibrated from the start; created from its criteria alone, it scores with estimated weights until you [calibrate](/concepts/calibration#calibrate-a-scoring-model) it. See [Creating a scoring model](/concepts/scoring-models#creating-a-scoring-model). To add questions of your own, send `add_questions` ([Changing questions](/concepts/scoring-models#changing-questions)).

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

Creates a scoring model and returns `202` at once with its `model_id` and a `job_id`. Wait for the [job](/reference/get-job-status), then [score records](/reference/score). Create it from:

- **Its `name` and `criteria` alone.** Finic writes its questions from the criteria and estimates how much each one counts. It's ready in less than a minute and scores any record; [calibrate](/reference/calibrate) it later with labeled examples or outcomes to fit it to your data.
- **Labeled examples in `data`:** past records whose outcomes you know. It's calibrated to them from the start, in about two minutes. For what to send, see [Example data](/concepts/scoring-models#example-data).

To try it here, open the playground and pick the **300 sample payments** example: they're synthetic card payments in the same shape as the score example (also as [sample-payments.csv](/examples/sample-payments.csv)). A scoring model built on sample data is only for trying Finic out.

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

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of object or string |  | Optional. The examples: a JSON array of objects, or CSV text with a header row. Every row needs `is_bad`: `true` when the outcome was bad, `false` when good (also `1`/`0`). At least 100 rows with 20 or more of each outcome; up to 2,000 are used. Row rules are under [Rules](/concepts/scoring-models#rules). Without `data`, send `criteria`. |
| `name` | string | yes | Required. A few words for people to recognize the scoring model by, such as "Card-not-present payment fraud". |
| `criteria` | string |  | What the decision is and what a bad outcome (`is_bad`) means, such as "Card-not-present payments. Bad: charged back as fraud within 90 days." Required without `data`, since Finic writes the questions from it; with `data`, optional context. |
| `add_questions` | array of string |  | Optional. Your own yes/no questions about a record, used alongside Finic's, such as "Was the account opened less than a week before the payment?". Created from examples, the scoring model uses the ones that help, and the others are listed as not used on its page in the Finic Portal; created from criteria alone, it uses them all, with weights Finic estimates. Up to 20 at a time, and 50 per scoring model. |

Example:

```json
{
  "name": "Card-not-present payment fraud",
  "criteria": "Card-not-present payments at an online store. Bad: the payment was charged back as fraud within 90 days."
}
```

### Responses

- **202**: The scoring model is being created.

| Field | Type | Always | Description |
| --- | --- | --- | --- |
| `model_id` | string | yes | The scoring model's id, `scm_…`, for scoring and calibrating. |
| `job_id` | string | yes | The job creating it, `job_…`. |
| `request_id` | string | yes | `req_…`, the same as the `X-Request-Id` header. |

```json
{
  "model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9",
  "job_id": "job_01M4XZXNCRZBPXV30MSF7RN5H3",
  "request_id": "req_01M4Y7FASG9DB7MMWCS672J0JD"
}
```

- **400**: `invalid_request`: `name` is missing, neither `criteria` nor `data` was sent, or the examples break a rule. The message says which, for example:
  - `criteria is required to create a scoring model without examples: what the decision is and what a bad outcome means, which Finic writes its questions from. Or send labeled examples as data.`
  - `A scoring model needs at least 100 labeled rows; got 64.`
  - `A scoring model needs at least 20 rows with is_bad true and 20 with it false; got 12 and 140.`
  - `Row 12 has no is_bad field. Every row needs is_bad: true when the outcome was bad, false when it was good.`
  - `Row 7: is_bad must be true or false (or 1 or 0); got "maybe".`
  - `data is not valid CSV: record on line 9: wrong number of fields.`

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

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

- **429**: `rate_limited`: 100 scoring models created in the last 24 hours, or over the [request rate](/reference#rate-limits).

- **503**: `overloaded`: creating scoring models isn't available right now. Try again later.