Why you would use it
A score that is a week old is a score nobody trusts, and the first time someone spots a stale number they stop looking at the panel.
You do not have to set anything up to avoid that. Opening a customer recalculates the score if it has gone stale, so it is already current for whoever is looking. What a scheduled nightly run adds is history: a snapshot for every customer, including the ones nobody opened, which is what makes the trend arrow and the previous score real rather than patchy.
If you read nothing else: scores are current without any scheduling. Schedule the nightly run if you want trends and previous scores to be complete.
The three routes
Route | When it runs | Why it exists |
Batch | On a schedule you set, or on demand from Settings. | Keeps history complete, including for customers nobody opened that day, so trends and previous scores are real. |
On opening a record | When the stored score is older than your freshness window. | Makes the score effectively live for whoever is looking, at no standing cost. |
Refresh | Immediately, when a user clicks it on the panel. | Confirms the effect of answering a check or changing a setting. |
The freshness window
Set Stale after (minutes) in Settings. The default is 1440, which is a day, and the minimum is 5. A setting of 15 reads as real time to anyone opening a record while keeping recalculation rare.
Running it from Settings
Score all records now on the Record Scoring page runs a full sweep for your company in the background, with progress shown. It is safe to run again, and a large company will not tie up your session. Use it after a significant configuration change, or at go live.
Scheduling the nightly run
For unattended runs, call the Record Scoring API from your scheduler, per company and per enabled metric.
Endpoint | Purpose |
| Starts the sweep. Returns immediately and runs in the background. One run per company per metric at a time, and safe to repeat. |
| Scores every customer, not only those already scored. Use once at go live. |
| Progress of the last run: running, done or failed, and how many records were processed. |
| One record's score, band, effective band, trend and override facts. |
| Query by score: filter by band or score range, paged, highest first. |
The company is taken from the authenticated token, never from anything you pass in, so a token can only ever touch its own company's data.
Permissions
These endpoints accept a token holding api-all, or the narrower api-record-scoring role. Give your scheduler the narrow one, so a routine job cannot do anything else. The role is created by a database update; if it is not available to grant yet, that update has not been applied on your environment.
What a run does
Recalculates each customer and stores the score, band and per check evidence.
Writes one history snapshot per customer per day, which is what the previous score and the trend arrow read.
Updates the six customer fields used by grids and reporting.
Skips excluded customers, and skips linked accounts where you score parent accounts only.
Never removes a manual override.
Choosing a schedule
Nightly outside business hours suits most companies: it keeps history complete, and the freshness window handles everything during the day. If you want fresher trend data for reporting, run it more often rather than shortening the freshness window, which only affects records people open.
Support
Support page: thelayer.com/support
Email: [email protected]
Telephone: 03333 222 000

