# NHS Dental Contract Performance & Capacity Signals (`starshaped_bullsnake/nhs-dental-contract-performance-capacity-signals`) Actor

Compare official NHS dental contract delivery with commissioned UDA targets and surface material divergence and target-change signals.

- **URL**: https://apify.com/starshaped\_bullsnake/nhs-dental-contract-performance-capacity-signals.md
- **Developed by:** [Starshape Tools](https://apify.com/starshaped_bullsnake) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 dental contract performance / capacity signals

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## NHS Dental Contract Performance & Capacity Signals

This Actor compares official NHS dental contract delivery with commissioned UDA targets and surfaces material divergence and commissioned-activity change signals. It emits one consolidated item per general dental contract. It is not a generic CSV downloader.

### Signals

- `DELIVERY_PACE_BELOW_TARGET`: delivery is at or below 70% of the straight-line commissioned pace and at least 750 UDA behind.
- `DELIVERY_PACE_ABOVE_TARGET`: delivery is at or above 130% of straight-line commissioned pace and at least 750 UDA ahead.
- `CONTRACT_TARGET_INCREASED` and `CONTRACT_TARGET_DECREASED`: the annual general-dental UDA target changed by at least 500 UDA and 10% between consecutive contractual snapshots.

Pace is a simple year-to-date comparison for contracts covering the full financial year: the Actor sums monthly `UDA_DELIVERED` from April through the common reporting month, then compares it with `annual target × months elapsed ÷ 12`. Contracts with missing Activity data or partial-year contractual periods are not treated as zero-delivery pace signals. Target-change signals require comparable full-year contractual snapshots with unchanged recurring service-line composition. April and May comparisons are based on few months and may be volatile. These signals are not forecasts of year-end failure, claims of actual spare clinical capacity or appointment availability, NHS performance judgements, guaranteed opportunities, or evidence of financial distress.

### Input

- `mode`: `live` (default) resolves current official data, or `sample` uses embedded fixtures and makes zero HTTP requests.
- `maxItems`: maximum ranked outputs after signal consolidation (default 100).
- `minDeliveryGapUda`: optional pace-gap threshold (default 750 UDA).
- `paceThresholdPercent`: optional divergence from 100% straight-line pace (default 30%).

Use `{ "mode": "sample" }` for a deterministic, credential-free demonstration with at least three normal Dataset items. The Actor is stateless: it does not use persistent state or suppress repeated outputs.

### Sources and method

The live Actor uses only the public NHS Business Services Authority Open Data Portal CKAN API and direct CSV files:

- [English Contractor Monthly General Dental Activity](https://opendata.nhsbsa.net/dataset/english-contractor-monthly-general-dental-activity)
- [English Contractor Monthly General Dental and Orthodontic Contractual Dataset](https://opendata.nhsbsa.net/dataset/english-contractor-monthly-general-dental-and-orthodontic-contractual-dataset)

It dynamically selects the latest month present in both datasets, requires the immediately preceding contractual month, resolves every activity month from April to the current snapshot once, and joins locally by `CONTRACT_NUMBER`. NHSBSA contractual data may contain multiple service-line rows per contract. The Actor deduplicates identical rows and aggregates compatible service-line records by contract before calculating signals; contracts with conflicting core contractual metadata are excluded rather than guessed. Contractual data contains all service lines held by general dental contracts; the MVP uses only aggregated `GENERAL_DENT_UDA_TARGET` and does not create orthodontic signals. Required semantic fields fail closed if they disappear. Explicit aliases cover documented compatible renames, including `RECURRING_IND` to `RECURRING_INDICATOR`; location fields are optional and support `LSOA11_CODE`/`LSOA21_CODE`.

### Limitations and attribution

The sources are monthly management information, not real-time. FP17 activity is delayed because submissions can be made after treatment, and contractual data also has a publication lag. Straight-line YTD pace does not account for seasonality, commissioning arrangements, contract timing, corrections, or locally commissioned services that may not be fully represented. Targets and historical records can change. Contract delivery headroom is not the same as actual appointment capacity. No performer-level personal data is emitted.

Contains information supplied by NHS Business Services Authority. Source datasets indicate reuse under the [Open Government Licence 3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/); attribute NHS Business Services Authority when reusing results. This Actor is independent and does not imply NHS or NHSBSA endorsement.

# Actor input Schema

## `mode` (type: `string`):

Live uses official NHSBSA data; sample uses deterministic embedded fixtures with zero HTTP requests.

## `maxItems` (type: `integer`):

Maximum ranked contract signal items written to the Dataset.

## `minDeliveryGapUda` (type: `number`):

Minimum absolute UDA gap for pace signals. Default 750.

## `paceThresholdPercent` (type: `number`):

Percentage below or above straight-line pace. Default 30, producing 70% and 130% boundaries.

## Actor input object example

```json
{
  "mode": "live",
  "maxItems": 100
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("starshaped_bullsnake/nhs-dental-contract-performance-capacity-signals").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("starshaped_bullsnake/nhs-dental-contract-performance-capacity-signals").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call starshaped_bullsnake/nhs-dental-contract-performance-capacity-signals --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,starshaped_bullsnake/nhs-dental-contract-performance-capacity-signals"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Y2n0UdtW1xSrBlmR6/builds/wjQ5gJTUwbq6Hr0mX/openapi.json