# create_score (/reference/create-score)



Up to 100 new scores per organization per day.

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

Creates a score from past records whose outcomes you know, and returns `202` at once with its `model_id` and a `job_id`. Creating takes about 5 to 10 minutes: wait for the [job](/reference/get-job-status), then [score records](/reference/score). For what to send, see [Example data](/concepts/scores#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 score 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 | yes | 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/scores#rules). |
| `description` | string |  | Optional. What the decision is and what `is_bad` means. |

Example:

```json
{
  "description": "Card-not-present payments. is_bad: the payment was charged back as fraud within 90 days.",
  "data": [
    {
      "amount_usd": 2400,
      "merchant_category": "electronics",
      "account_age_days": 19,
      "new_device": true,
      "billing_country": "US",
      "ip_country": "NG",
      "is_bad": true
    },
    {
      "amount_usd": 58.12,
      "merchant_category": "grocery",
      "account_age_days": 1260,
      "new_device": false,
      "billing_country": "US",
      "ip_country": "US",
      "is_bad": false
    }
  ]
}
```

### Responses

- **202**: The score is being created.

| Field | Type | Always | Description |
| --- | --- | --- | --- |
| `model_id` | string | yes | The score'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`: the examples break a rule. The message says which, for example:
  - `A score needs at least 100 labeled rows; got 64.`
  - `A score 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 scores created in the last 24 hours, or over the [request rate](/reference#rate-limits).

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