create_score

POST /v1/scores creates a score from labeled examples and returns its model_id and a job to wait for.

Up to 100 new scores per organization per day.

POST

/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, then score records. 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 score built on sample data is only for trying Finic out.

Request body

multipart/form-data or application/json

Field	Type	Description
`data`required	array of object or string	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.
`description`	string	Optional. What the decision is and what `is_bad` means.

Field	Type	Description
`file`required	string	The examples, as CSV with a header row or a JSON array, every row with `is_bad`.
`description`	string	Optional. What the decision is and what `is_bad` means.

Responses

The score is being created.

Field	Type	Description
`model_id`	string	The score'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`: 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.
`503`	`overloaded`: creating scores 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/scores' \  -H "Authorization: Bearer $FINIC_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "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    }  ]}'

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