# Glossary

Terms used throughout the ThinkLP APIs and this documentation.

## Records and domains

**Theft Case** — A theft investigation. Backed by the Salesforce
`ThinkLP__Investigation__c` object. Its records use the `a0n…` ID prefix.
Managed through the `/theft-cases` endpoints.

**Canonical record** — A standalone, reusable master record for a Vehicle,
Person, or Item, managed through its own domain (`/vehicles`, `/persons`,
`/items`). The same canonical record can be referenced by many theft cases.

**Location** — A canonical store/site record (name, address, region, district,
coordinates, and so on). Retrieved and updated by id through `/locations`. Not
created through the API.

**Junction record** — The link between a theft case and a canonical record,
carrying case-specific context. There are three: **Involved Vehicle**,
**Involved Person**, and **Case Item**. A junction holds fields that describe
the record's role in that case: notes, quantity, plate state, and so on. Those
fields are separate from the canonical record's own data.

**Involved Vehicle / Involved Person / Case Item** — The three junction types
linking a vehicle, person, or item to a theft case.

## Request and response concepts

**Envelope** — The `{ detail, fieldSpecs }` response shape returned by canonical
retrieve, create, and update. `detail` is the record. `fieldSpecs` is form
metadata. See [Field metadata](./field-metadata.md).

**fieldSpec** — One entry in `fieldSpecs` describing a single field (label,
type, required, options, and so on).

**Preview** — A read-only snapshot of a referenced canonical record. The API
embeds it on a junction response, for example `vehiclePreview`, `personPreview`,
or `itemPreview`. You can display the record without a second call. The API
returns `null` when the referenced record is unavailable.

**Lookup** — A convenience read that resolves a single canonical record by a
natural key: `by-plate` for vehicles, `by-sku` for items. Returns a flat record
(no envelope).

**Search** — A filtered query over a domain that returns a bare array of
lightweight preview records. Requires at least one filter criterion.

**Attach / Detach** — Adding (`POST` a sub-resource) or removing (`DELETE` with
`ids`) a junction link between a theft case and a canonical record.

**Dedup-on-attach** — When you attach a vehicle by plate or an item by SKU, the
API searches for a matching canonical record. It reuses the match when one
exists, and creates a new record when none does. You never create a duplicate.

**Cascade update** — Managing junction links inline by embedding
`involvedVehicles[]`, `involvedPersons[]`, or `caseItems[]` in a
`PUT /theft-cases` body, rather than calling the sub-resource endpoints.

## Errors

**Error envelope** — The `{ code, message }` shape returned on failure. Branch
your integration on `code`. Treat `message` as informational. See
[Errors](./errors.md).

## Insights (case linkage)

**Frontier transaction** — A point-of-sale transaction record captured by
ThinkLP Frontier, used as the source for creating a theft case through the
`/insights` endpoints.

**Transaction snapshot** — The copy of a Frontier transaction's key fields,
stored when the transaction is linked to a case. The case reflects the
transaction as it was at link time.

**Case linkage** — Creating a theft case from one or more Frontier transactions
via `POST /insights/cases`. The transaction's employee is added as an Involved
Person and its POS line items become Case Items on the new case.

**Badge** — A per-transaction indicator returned by `/insights/cases/badges`
showing whether a transaction is already linked to a case.
