Conventions

These conventions apply across every ThinkLP API domain.

Requests and responses

• All request and response bodies are application/json.
• Send your access token as a bearer token on every request (see
  Authentication).
• All traffic is over HTTPS.

Record identifiers

Records are identified by their Salesforce record ID (15- or 18-character).
Retrieve a single record by passing its id as a query parameter:

GET /theft-cases?id=a0nXXXXXXXXXXXXXXX

Creating and updating

• Create — POST the record body to the collection. A successful canonical
  create returns 200 OK with the record envelope (see Response shapes).

  POST /vehicles

• Update — PUT the record body, identifying the record with ?id=. If the
  body also contains an id, it must match the query parameter or the request
  is rejected with BAD_REQUEST. A successful update returns 200 OK with the
  record envelope.

  PUT /persons?id=a16XXXXXXXXXXXXXXX

Not every canonical domain supports every verb. Locations is read-only —
load it by id with GET /locations?id=; it has no create, update, or search.

Response shapes

The shape of a successful response depends on the kind of endpoint:

• detail carries the record itself; fieldSpecs is per-field metadata
  (label, type, required, options, and so on) you can use to render a form. The
  fieldSpecs entries share one shape across every domain.
• Lookups and search are convenience reads and deliberately skip the envelope.

Insights (case linkage)

The /insights/… endpoints are a distinct surface for creating theft cases from
Frontier point-of-sale transactions. They share the same authentication and
{ code, message } error envelope, but use purpose-specific request and response
shapes rather than the { detail, fieldSpecs } envelope:

• POST /insights/cases creates a case from an embedded transaction set and
  returns 201 with a summary object — caseId, caseUrl, and counts of the
  linked transactions, involved persons, and case items (plus any skipped
  employees) — not the envelope.
• GET /insights/cases/{caseId}/transactions returns a bare array of the
  transactions linked to a case.
• GET /insights/cases/badges?transactionIds=… returns an object keyed by
  transaction id; each value indicates whether that transaction is already linked
  to a case (null if not).

See Errors for the Insights-specific error codes.

Related records on a case

A theft case links to the vehicles, persons, and items involved in it. Manage
those links with sub-resources:

POST   /theft-cases/{caseId}/involved-vehicles     Attach a vehicle
DELETE /theft-cases/{caseId}/involved-vehicles?ids=a1X...,a1Y...   Detach vehicles

To remove links in bulk, pass a comma-separated list of link IDs in the ids
query parameter. The same pattern applies to involved-persons and
case-items.

You can also manage links inline on the case: a PUT /theft-cases?id= body
may embed involvedVehicles[], involvedPersons[], and caseItems[] arrays to
create, update, or replace those links in the same call that updates the case.
Send the complete set you want on the case — omitting an entry removes the link.

Search and lookup

Domains that support discovery expose two styles of endpoint:

• Search — filter a collection by one or more criteria. At least one filter
  must be supplied; a search with no criteria is rejected with
  UNDER_SPECIFIED_SEARCH. The response is a bare array of lightweight preview
  records (not the envelope).

  GET /persons/search?lastName=Smith&firstName=Jane
  GET /vehicles/search?make=Ford&state=NY

• Lookup — resolve a single record by a natural key:

  GET /vehicles/by-plate?plateNumber=ABC123&state=NY
  GET /items/by-sku?sku=SKU-00042

Pagination

Where a search endpoint supports paging, it accepts limit and offset:

GET /persons/search?lastName=Smith&limit=25&offset=50

• limit caps the number of records returned.
• offset skips the given number of records. To page through results, increase
  offset by limit on each request.

Dates and times

• Dates use ISO 8601 calendar format: YYYY-MM-DD (for example,
  2026-07-08).
• Timestamps use ISO 8601 / RFC 3339 date-time format in UTC (for example,
  2026-07-08T14:30:00Z).
• Times (time-only fields) are returned as HH:MM:SS (for example,
  14:30:00). A value sent without seconds (14:30) is echoed back with them.