---
title: "Group unassigned source records by site signal, largest groups first"
method: GET
path: "/sites/suggestions"
tags: ["Sites"]
---

# Group unassigned source records by site signal, largest groups first

`GET /sites/suggestions`

Groups the organization's live source records that carry neither a site nor an entity by the
normalized supply point, meter number, account number and location text they carry (a record
appears once per (kind, value), however many fields carry it). Each group shows the active site
its value already maps to, if any, and conflictingCount (see SiteSuggestion). Signal kinds rank
supply_point > meter_number > account_number > location_text.
The read runs two statements (the count, then the grouping), each under the server's statement
timeout, so one call can take up to twice that timeout before answering 503.
Error codes: 400 VALIDATION_ERROR (limit outside 1-200); 503 SUGGESTIONS_TIMEOUT.

## Query parameters

- `limit` integer

## Response `200`

Suggestion groups

- SiteSuggestionsResponse
  - `data` object, required
    - `items` SiteSuggestion[], required
      - `conflictingCount` integer, required — Records in the group whose best matched site comes from a signal kind ranked above the group's kind and differs from the group's matched site (for an unmatched group: any such site). Assigning the group to its matched site (for an unmatched group, to a site that no stronger signal of its records names) skips exactly these records.
      - `kind` 'supply_point' | 'meter_number' | 'account_number' | 'location_text', required
      - `latestAt` string, date-time, required
      - `matchedSiteId` string, nullable, required
      - `matchedSiteName` string, nullable, required
      - `recordCount` integer, required
      - `sampleValue` string, required — One value as a document states it
      - `value` string, required — Normalized signal value
    - `truncated` boolean, required
    - `unassignedRecordCount` integer, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `503` — SUGGESTIONS_TIMEOUT: the grouping took too long

## Changes

- **2026-10-02** `766c2a40e369` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greentally/apis/esgai-api/changes/sites/suggestions/get.md)

---

[API](https://skmtc.dev/greentally/apis/esgai-api.md) · [All operations](https://skmtc.dev/greentally/apis/esgai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greentally/apis/esgai-api/revisions/4189686230ca?raw)