---
title: "Resolve an incentive id (or id prefix)"
method: GET
path: "/incentives/id/{uid}"
tags: ["Incentives"]
---

# Resolve an incentive id (or id prefix)

`GET /incentives/id/{uid}`

## Request

- Base URL: `https://apis.wattbuy.com/v3`
- URL: `https://apis.wattbuy.com/v3/incentives/id/{uid}`
- Auth: API key in header `x-api-key`

Resolves a constructible incentive id — the `id` field on /incentives records — to the record it identifies,
regardless of status (an expired program stays resolvable, so a stored quote can show it as expired).

The id is `wb1:{state}:{authority_type}:{authority_ref}:{tech}:{subtype}:{program_type}:{variant}[:{slug}]`,
so any colon-delimited **prefix** is also valid and returns the matching set: an exact match wins
(`count: 1`); otherwise `matches` holds every record under the prefix and `disambiguate_on` names the next
segment with its distinct values. `count: 0` with `moved_to` means the id was re-minted (data correction) —
refetch with the new id. `matches` is capped at 200 (`truncated: true`).

## Path parameters

- `uid` string, required

## Response `200`

Lookup result

- object
  - `status` string
  - `uid` string: The id/prefix as resolved.
  - `count` integer: Total matching records (may exceed matches.length when truncated).
  - `matches` object[]: Records in the same shape as /incentives upfront[] / ongoing[] rows, plus `kind`. No sizing inputs here, so estimated_amount is populated only for flat amounts.
    - `kind` 'upfront' | 'ongoing'
    - `id` string
    - `status` string
  - `disambiguate_on` object: Present when count > 1 — the next id segment and its distinct values among the matches.
    - `segment` integer
    - `name` 'state' | 'authority_type' | 'authority_ref' | 'tech' | 'subtype' | 'program_type' | 'variant' | 'slug'
    - `values` string[]
  - `moved_to` string: Present with count 0 when the id was re-minted; refetch with this id.
  - `truncated` boolean: Present (true) when matches was capped at 200.

## Other responses

- `400`: Malformed id (must start with `wb1` and be colon-delimited tokens)
- `500`: Internal server error

## Changes

- **2026-11-03** `443ce1657edb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/wattbuy/apis/wattbuy-apis/changes/incentives/id/:uid/get.md)

---

[API](https://skmtc.dev/wattbuy/apis/wattbuy-apis.md) - [All operations](https://skmtc.dev/wattbuy/apis/wattbuy-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/wattbuy/apis/wattbuy-apis/revisions/443ce1657edb?raw)
