calibrate

POST /v1/calibrate sends the outcomes of records you scored, so the score improves over time.

Up to 10 calibrations per score per day. See Calibration.

POST

/v1/calibrate

Sends the outcomes of records you scored, matched by score_id, and updates the score with them. Returns 202 with a job_id; score calls after the job completes use the updated score. One calibration at a time per score. Rows whose score_id wasn't sent to this score are skipped; sending an outcome again replaces it. A failed request records none of its outcomes.

Request body

application/json or multipart/form-data

Field	Type	Description
`model_id`required	string	The score these outcomes are for.
`data`required	array of object or string	The outcomes: a JSON array of rows, or CSV text with a header row. A `model_id` in a row must match; other row fields are ignored.

Field	Type	Description
`score_id`required	string or number	The `score_id` you sent to `POST /v1/score`, once per request.
`is_bad`required	boolean or number or string	`true` when the outcome was bad. Also `1`/`0` or `"yes"`/`"no"`.

Responses

The calibration is running.

Field	Type	Description
`job_id`	string	The calibration's job, `job_…`.
`matched`	integer	Rows that matched a call to this score.
`unmatched`	integer	Rows skipped.
`request_id`	string	`req_…`, the same as the `X-Request-Id` header.

Status	Type and when
`400`	`invalid_request`: `model_id` is missing, a row breaks a rule, or no `score_id` matches a call to this score.
`401`	`authentication_error`: the API key is missing, unknown, revoked or expired.
`404`	`score_not_found`: no score with this `model_id` in your organization.
`409`	`score_not_ready`: the score is still being created, or creating it failed. `calibration_in_progress`: a calibration is already running. Send these again when its job completes.
`413`	`request_too_large`: over 2 MB, or the record is too large.
`429`	`rate_limited`: 10 calibrations of this score in the last 24 hours, or over the request rate.

Every error has the same shape; see Errors.

Examples

Example Request

curl -X POST 'https://api.finic.ai/v1/calibrate' \  -H "Authorization: Bearer $FINIC_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9",  "data": [    {      "score_id": "pay_88213",      "is_bad": true    },    {      "score_id": "pay_88214",      "is_bad": false    }  ]}'

Example ResponseSchema

{  "job_id": "job_01M4YY4AZRJ8NR5QFRW628CJ5G",  "matched": 2,  "unmatched": 0,  "request_id": "req_01M4YPJNK0SZGEQS0A76EEND4N"}

Request body

Each row: data[]

As multipart/form-data

Responses

202 Accepted

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

Examples