create_scoring_model

POST /v1/scoring_models creates a scoring model from its criteria or from labeled examples, and returns its model_id and a job to wait for.

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 it. See Creating a scoring model. To add questions of your own, send add_questions (Changing questions).

POST

/v1/scoring_models

Creates a scoring model and returns 202 at once with its model_id and a job_id. Wait for the job, then score records. 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 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.

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). A scoring model built on sample data is only for trying Finic out.

Request body

multipart/form-data or application/json

Field	Type	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. Without `data`, send `criteria`.
`name`required	string	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.

Field	Type	Description
`file`	string	Optional. The examples, as CSV with a header row or a JSON array, every row with `is_bad`. Without it, send `criteria`.
`name`required	string	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`	string	Optional. Your own questions, one per field (repeat it), or as a JSON array of strings. See `add_questions` in the JSON body.

Responses

The scoring model is being created.

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

Status	Type and when
`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.
`503`	`overloaded`: creating scoring models isn't available right now. Try again later.

Every error has the same shape; see Errors.

Examples

curl -X POST 'https://api.finic.ai/v1/scoring_models' \  -H "Authorization: Bearer $FINIC_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "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."}'

Example ResponseSchema

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

Request body

As multipart/form-data

Responses

202 Accepted

Errors (400, 401, 413, 429, 503)

Examples