score

POST

/v1/score

Scores one record with a score you created: 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.

Request body

application/json or multipart/form-data

Field	Type	Description
`model_id`required	string	The score's id, from Create a score.
`score_id`required	string	Your id for this record, unique within the score. Send it back with the outcome to calibrate.
`data`required	object or array of object or string	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.
`update_schema`	boolean	Score it and make its fields the schema from now on.

Field	Type	Description
`model_id`required	string	The score's id.
`score_id`required	string	Your id for this record.
`file`required	string	The record: CSV with a header and one row, or a JSON object.
`skip_schema_validation`	boolean
`update_schema`	boolean

Responses

The score.

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

Status	Type and when
`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. Retry with backoff.
`503`	`overloaded`: temporarily at capacity. Retry with backoff.

Every error has the same shape; see Errors.

Examples

Example Request

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

Example ResponseSchema

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

Request body

As multipart/form-data

Responses

200 OK

Errors (400, 401, 402, 404, 409, 413, 429, 503)

Examples