ThinkLP
TheftCase API

TheftDto

The theft case body.
id
​string | null

Salesforce Investigation record Id

investigationType
​string | null

Investigation type picklist value (e.g. External Theft, Internal Theft). Immutable after create.

incidentDate
​string | null · date

Date of the incident (YYYY-MM-DD)

incidentTime
​string | null

Time of the incident as string (HH:MM)

primaryLocationId
​string | null

Salesforce Id of the primary location record. Send this or locationNumber; if both are sent they must name the same location.

locationNumber
​string | null

Location Number of the primary location, the location's unique external id. Returned on every response (null when the case has no location). On POST and PUT it names the primary location instead of primaryLocationId; it resolves through the Location Number lookup, which ignores letter case, surrounding whitespace and apostrophes and falls back to the unpadded number. A number that matches no location, or several, returns 422 NATURAL_KEY_NOT_FOUND. If primaryLocationId is also sent it must name the same location, or the API returns 400 INVARIANT_VIOLATION.

reportedAt
​string | null · date-time · readOnly

When the case was reported: the record's creation time (read-only). Ignored on writes. Null in a MAPPED org whose mapping does not provide it.

status
​string | null

Case status picklist value (Open, Closed, Pending Assignment, Pending Approval)

incidentType
​string | null

The Incident Type value the org stores, returned as stored. On a write without incidentTypeKey, the value is stored as given and is never validated against the org's values. Sent together with incidentTypeKey, it is kept only when it already belongs to that key.

incidentTypeKey
​string | null

The domain Incident Type key the stored incidentType belongs to, for example shoplifting or robbery; null when the stored value belongs to no key. Returned on every response that carries detail. On a write, the package stores the org value the key maps to: A key with no mapping is stored as incidentTypeLabel, or as the key itself when no label is sent. A request that sends both keeps incidentType when it already belongs to the key, so a body read from a GET and sent back unchanged keeps the stored value; otherwise the key wins. The package ships a fixed default map from the domain's base list of keys to their labels (shoplifting is stored as Shoplifting, robbery as Robbery).

Example: robbery
incidentTypeLabel
​string | null · writeOnly

Write only, ignored on a response. The value to store when incidentTypeKey has no mapping in the org.

Example: Gift Card Fraud
methodPrimary
​string | null

Primary theft method picklist value

methodSecondary
​string | null

Secondary theft method picklist value

narrative
​string | null

Free-text narrative description of the incident.

​object

Tenant-owned case values, keyed by the domain property key from the case mapping, never a Salesforce field API name. Values are strings. POST writes them on the Investigation in the same request. A key that is not a custom property returns 422 CUSTOM_PROPERTY_NOT_DEFINED. A required key that is blank or absent on POST returns 422 CUSTOM_PROPERTY_REQUIRED. A value that is not a string, a value that does not convert, a value for a field the user cannot create, or a DML rejection of the field, returns 422 CUSTOM_PROPERTY_NOT_WRITABLE. Those refusals name the key in field, not the field API name, and do not include the value. GET returns the stored values as strings, or an empty object when the case has none. PUT ignores this field and does not change stored values. Required keys are enforced only on POST.

initialCaseValue
​number | null

Initial estimated value of the case. Immutable after create.

currencyIsoCode
​string | null

ISO 4217 currency code that all monetary fields are denominated in. In a response, every detail carries it and it is never null: the Estimated Loss currency, else the promissory amount currency, else the case's own currency. In a POST or PUT body it is optional: omit it or send null to keep the default. POST and PUT refuse a code the org cannot hold with 422 CURRENCY_NOT_SUPPORTED: a single-currency org holds only its own currency, a multi-currency org holds its active currencies.

totalCaseValue
​number | null · readOnly

Total calculated value of all stolen items (read-only rollup)

totalItems
​number | null · readOnly

Total number of items involved in the case (read-only rollup)

totalCaseValueRecovered
​number | null · readOnly

Total value recovered (read-only rollup)

uuid
​string | null

External UUID for cross-system reference and unique across cases. New values are stored in lower case and looked up in lower and upper case, so a value that differs only in letter case is the same uuid, except for a stored mixed-case value, which is a known gap. A POST that repeats a stored uuid returns 409 DUPLICATE_UUID with the stored case's id. Immutable after create: an update that repoints it at a different value is rejected with 400 IMMUTABLE_FIELD. A PUT that sets a uuid held by another case is rejected with 409 DUPLICATE_UUID.

investigatorId
​string | null

Salesforce User Id of the assigned investigator

priority
​string | null

Case priority picklist value, as stored. Open-set: not enumerated. Omitting it on an update keeps the stored value.

outcome
​string | null

Case outcome picklist value, as stored. Open-set: not enumerated. Omitting it on an update keeps the stored value.

caseReport
​string | null

Case report, as rich text (HTML). Omitting it on an update keeps the stored value.

executiveSummary
​string | null

Executive summary, as rich text (HTML). Omitting it on an update keeps the stored value.

investigationPlan
​string | null

Investigation plan, as rich text (HTML). Omitting it on an update keeps the stored value.

promissoryAmount
​number | null

Promissory note amount

damages
​string | null

Damages picklist value

damageDescription
​string | null

Free-text description of damages

actionsTaken
​string | null

Actions taken during the incident

preventativeActions
​string | null

Preventative actions recommended

policeNotified
​string | null

Yes/No picklist indicating if police were notified

policeNotifiedTime
​string | null · date-time

Datetime when police were notified (ISO 8601)

policeArrivalTime
​string | null · date-time

Datetime when police arrived (ISO 8601)

policeDepartment
​string | null

Name of the police department

policeOfficerName
​string | null

Name of the responding police officer

policeOfficerBadgeNumber
​string | null

Badge number of the responding police officer

policeReportNumber
​string | null

Police report number

policeDisposition
​string | null

Police disposition picklist value

concealmentLocation
​string | null

Location where items were concealed

concealmentMethod
​string | null

How the items were concealed, as reported. Any text is accepted.

pointOfEntry
​string | null · maxLength: 100

How the offender got into the location, free text up to 100 characters. Accepted on any Investigation Type.

reportDate
​string | null · date

Date the incident was reported

reportTime
​string | null

Time the incident was reported (HH:mm:ss)

closedDateTime
​string | null · date-time

Date/time the case was closed (read-only)

incidentNumber
​string | null · readOnly

Auto-generated incident number (read-only)

​array | null

People associated with this case (suspects, witnesses, employees, law enforcement, and so on). Ordered by Salesforce Id ascending as an insertion-order proxy. Round-trips on GET, PUT, and POST. The insert, update, and delete-orphan cascade applies on PUT.

Body-shape semantics:

  • An omitted field preserves the existing children (no-op).
  • An empty array deletes all children.
  • An explicit null is treated as omitted (no-op).
  • An unknown id in the payload (a stale client cache) is rejected as BAD_REQUEST.

POST entries must omit id. Concurrency is last-write-wins. PATCH for surgical updates is deferred.

​array | null

Vehicles associated with this case.

Body-shape semantics:

  • An omitted field preserves the existing junctions (no-op).
  • An empty array deletes all junctions.
  • An explicit null is treated as omitted (no-op).

Each entry supplies a vehicleId, reported vehicle details such as plate, plateState and vin, or both. The reported details are stored on the involvement, and a reported plate or VIN never links a Vehicle; only a vehicleId does. A vehicleId that names no Vehicle returns 422 NATURAL_KEY_NOT_FOUND. vehicleId is immutable after create, and a change is rejected with 400 IMMUTABLE_FIELD. A PUT may list a stored vehicle by involvementId alone, and the API updates that row.

​array | null

Items associated with this case.

Body-shape semantics:

  • An omitted field preserves the existing junctions (no-op).
  • An empty array deletes all junctions.
  • An explicit null is treated as omitted (no-op).

A non-empty array replaces the set. sku and itemId are optional but encouraged, and each entry needs at least one reported detail (sku, itemId, notes, quantity, valueAtIncident, category, upc, serialNumber, unitType, condition, itemName, merchandiseCategory, merchandiseType, brand, department, stockNumber or unitCost); an entry with none returns 400 INVARIANT_VIOLATION. On an entry that is being reported (one that names no stored case item by id or involvementId), a sku that matches exactly one Item, exactly after trimming and ignoring case, links that Item; a SKU that matches none or several is stored unlinked. A stored entry, however you name it, is never matched by SKU: its link changes only when you send an itemId. An itemId that names no Item returns 422 NATURAL_KEY_NOT_FOUND, and on a new entry an itemId and sku that name different Items return 400 INVARIANT_VIOLATION. itemId is immutable after create, and a change is rejected with 400 IMMUTABLE_FIELD. A PUT may list a stored item by involvementId alone, and the API updates that row.

InvolvedPersonDto

A person associated with a theft case. The link belongs to the case and is identified by `id`. An involvement describes its person in one or both of two ways: a canonical Person record through `personId`, and inline attributes stored on the involvement itself. At least one of `personId`, `employeeId`, `employeeNumber` or an inline attribute must be supplied. Naming an employee with `employeeId` finds or creates that employee's Person and links it; a person with no `personId` or `employeeId` has no unique identifier, so no Person is created and the involvement stays description-only. On a default org the involvement stores `firstName`, `lastName`, `dateOfBirth`, `physicalDescription` and `involvementId` on its own columns. Any other inline person attribute (for example `height` or `hairColor`) has no column and is rejected with `400 INVARIANT_VIOLATION` naming the property, never silently dropped; the referenced Person's own attributes read back only under `personPreview`. personRole is required in every case. The top-level name, date of birth and other description fields report only what the involvement itself stores, so a body read from the API and sent back unchanged writes nothing derived from the Person onto the involvement. Read paths populate `personPreview` with the Person's display name, type and attributes.
personRole
​string · enum · required

Role of the person in this case.

Enum values:
Suspect
Primary Suspect
Witness
Reporter
Current Employee
Former Employee
Customer
Law Enforcement
id
​string | null

Salesforce Id of the underlying junction record, assigned by Salesforce on insert. Omit on POST to create a new junction. Not the caller identifier of the involvement, which is involvementId.

personId
​string | null

Salesforce Id of the linked Person record. Optional: an involvement may be described only by inline attributes. When supplied, the lookup is stored and any inline description sent on the same request is stored on the involvement too (hybrid storage); the description is never copied onto the Person. On a case POST or PUT, an id that names no Person returns 422 NATURAL_KEY_NOT_FOUND with field personId. Immutable after create.

employeeId
​string | null · salesforce-id

The Salesforce Contact Id of an employee. On a canonical org, the API finds the Person attached to that employee, or creates one, and writes it as personId. Naming the same employee again reuses that Person. Inline description fields sent with employeeId are stored on the same involvement. The submitted employeeId is not stored on the involvement itself; reads return the Person's employee link as personPreview.employeeId. An unknown Contact id returns 422 NATURAL_KEY_NOT_FOUND with field employeeId and writes nothing. When personId is also supplied, both must name the same Person; otherwise the request is rejected with 400 INVARIANT_VIOLATION. On an org configured for inline person data, no Person is created: employeeId is written to the junction's own employee link as an ordinary inline attribute.

employeeNumber
​string | null

Employee Number of the employee, as an alternative to employeeId (write-only; never returned). Every number in the request resolves in one call; the employee is then handled exactly as if employeeId had been sent. A number that matches no employee, or several, returns 422 NATURAL_KEY_NOT_FOUND with field employeeNumber and the value sent. If employeeId is also sent it must name the same employee, or the API returns 400 INVARIANT_VIOLATION.

displayName
​string | null

Person display name. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

personType
​string | null · enum

Person type (EMPLOYEE or EXTERNAL). Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

Enum values:
EMPLOYEE
EXTERNAL
firstName
​string | null

Person's first name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

middleName
​string | null

Person's middle name. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

lastName
​string | null

Person's last name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

alias
​string | null

Person's alias or nickname. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

dateOfBirth
​string | null · date

Person's date of birth. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

sex
​string | null

Person's sex. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

ethnicity
​string | null

Person's ethnicity. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

email
​string | null

Person's email address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

phone
​string | null

Person's phone number. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

street
​string | null

Street address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

city
​string | null

City. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

state
​string | null

State or province. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

postalCode
​string | null

Postal code. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

country
​string | null

Country. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

height
​string | null

Person's height, as free text. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

weight
​number | null

Person's weight. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

eyeColor
​string | null

Person's eye color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

hairColor
​string | null

Person's hair color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

clothing
​string | null

Free-text description of clothing worn. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

identifyingFeatures
​string | null

Free-text description of identifying features such as scars or tattoos. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

externalId
​string | null

External system identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

thinkLPId
​string | null

ThinkLP-assigned identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

identificationNumber
​string | null

Identification number as the person reported it. Stored on the involvement itself with identificationType: set on create, returned on read.

identificationType
​string | null

Kind of identification identificationNumber holds, for example Driver's License, stored as reported. It is left blank when a number is sent without a type. Stored on the involvement itself: set on create, returned on read.

physicalDescription
​string | null · maxLength: 32768

Free-text physical description of the person, for an Incident that cannot name them. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set. Maximum 32768 characters. Never copied onto a Person.

involvementId
​string | null · maxLength: 36

Caller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. Stored on the junction's unique ThinkLPId column, which holds at most 36 characters, and returned on every read. Immutable after create: an update that sends a different value for a stored involvement returns 400 IMMUTABLE_FIELD; a value that differs only in case is the same value, and the stored spelling is kept. A value already held by another involvement, on this case or any other, or repeated inside one request, returns 409 DUPLICATE_INVOLVEMENT_ID; the comparison ignores case. Differs from id, the Salesforce record id that Salesforce assigns when the involvement is inserted: the caller mints involvementId before the record exists and resends it on retry, so a retried request is recognised and an update can find the stored involvement without the Salesforce id. Distinct from thinkLPId, which is an attribute of the Person.

​PersonPreviewDto | null · readOnly

Read-only preview of the referenced Person. Returned as null when the underlying Person is deleted, archived, or FLS-stripped for the running user (graceful degradation). The InvolvedPerson record itself is still valid case data.

isIdentityConfirmed
​boolean | null

Investigator-confirmed identity flag.

actionTaken
​string | null

Free-text description of action taken with this person.

chargesFiled
​string | null · enum

Tri-state charges-filed status (Yes / No / Pending). Backed by the ThinkLP__ChargesFiled__c picklist. Independent of apprehensionDateTime.

Enum values:
Yes
No
Pending
apprehensionDateTime
​string | null · date-time

When the person was apprehended.

notes
​string | null

Free-text investigator notes about this person.

readyForCivilRecovery
​boolean | null

Trigger flag set by investigator to request civil-recovery workflow.

civilRecoveryCreated
​boolean | null · readOnly

Stamped by downstream workflow when the civil-recovery record is created. Read-only on write. The API ignores any value you send.

PersonPreviewDto

Read-only preview of a referenced Person. Reads populate it. Writes ignore it. It is the one place the Person's own attributes appear: the top-level description fields of the involvement report only what the involvement stores.
displayName
​string | null

Person first name + last name composition.

personType
​string | null · enum

EMPLOYEE when the underlying Person has a populated employee Contact lookup, EXTERNAL otherwise.

Enum values:
EMPLOYEE
EXTERNAL
firstName
​string | null

The referenced Person's first name.

middleName
​string | null

The referenced Person's middle name.

lastName
​string | null

The referenced Person's last name.

alias
​string | null

The referenced Person's alias.

dateOfBirth
​string | null · date

The referenced Person's date of birth.

sex
​string | null

The referenced Person's sex.

ethnicity
​string | null

The referenced Person's ethnicity.

email
​string | null

The referenced Person's email.

phone
​string | null

The referenced Person's phone.

street
​string | null

The referenced Person's street.

city
​string | null

The referenced Person's city.

state
​string | null

The referenced Person's state.

postalCode
​string | null

The referenced Person's postal code.

country
​string | null

The referenced Person's country.

height
​string | null

The referenced Person's height.

weight
​number | null

The referenced Person's weight.

eyeColor
​string | null

The referenced Person's eye color.

hairColor
​string | null

The referenced Person's hair color.

clothing
​string | null

The referenced Person's clothing.

identifyingFeatures
​string | null

The referenced Person's identifying features.

externalId
​string | null

The referenced Person's external id.

thinkLPId
​string | null

The referenced Person's think l p id.

employeeId
​string | null · salesforce-id

The referenced Person's employee id.

InvolvedVehicleDto

One involved-vehicle link on a theft case, carried in the `involvedVehicles` array. The involvement stores the vehicle as the incident reported it, in `plate`, `plateState`, `vin`, `year`, `make`, `model`, `color`, `style` and `description`, and may also link a canonical Vehicle through `vehicleId`; the link never replaces what was reported. The top-level detail fields report only what the involvement itself stores, so a body read from the API and sent back unchanged writes nothing derived from the Vehicle onto the involvement. vehiclePreview carries the linked Vehicle's own details on reads, and the API ignores it on writes. A null vehiclePreview on the response means no Vehicle is linked, or signals graceful degradation when the referenced Vehicle is deleted, archived, or FLS-stripped. At least one of `vehicleId` or a reported detail must be supplied. A reported detail with no column on the involvement (for example `externalId`) is rejected with `400 INVARIANT_VIOLATION` naming the property, never silently dropped.
id
​string | null · salesforce-id

Salesforce record id of the Investigation_Vehicle__c junction row, assigned by Salesforce on insert. Null on POST cascade entry (new junction). Differs from involvementId, which the caller mints.

involvementId
​string | null · maxLength: 36

Caller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. Stored on the junction's unique ThinkLPId column, which holds at most 36 characters, and returned on every read. Immutable after create: an update that sends a different value for a stored involvement returns 400 IMMUTABLE_FIELD; a value that differs only in case is the same value, and the stored spelling is kept. A value already held by another involvement, on this case or any other, or repeated inside one request, returns 409 DUPLICATE_INVOLVEMENT_ID; the comparison ignores case.

vehicleId
​string · salesforce-id

Canonical Vehicle id. Optional: link a Vehicle only when you know it. An id that names no Vehicle returns 422 NATURAL_KEY_NOT_FOUND. A reported plate or VIN never sets it. Immutable after create.

plate
​string | null

Plate number as reported. Stored on the involvement and returned on read.

plateState
​string | null

Issuing state for the plate, as reported. A state outside the supported list returns 400 INVARIANT_VIOLATION naming plateState.

vin
​string | null · maxLength: 17

Vehicle identification number as reported, stored as free text. Not unique on the involvement, and never links a Vehicle.

make
​string | null

Vehicle make as reported.

model
​string | null

Vehicle model as reported.

year
​string | null · maxLength: 4

Vehicle model year as reported, carried as a string.

color
​string | null

Vehicle color as reported.

style
​string | null

Vehicle body style as reported.

description
​string | null

Free-text description of the vehicle.

externalId
​string | null

Source-system identifier for the vehicle. The default involvement has no column for it, so a value sent on write is rejected with 400 INVARIANT_VIOLATION unless the org maps it.

notes
​string | null

Case-side mutable context for the junction.

​VehiclePreviewDto | null · readOnly

Read-only preview of the referenced Vehicle. Returned as null when no Vehicle is linked, or when the underlying Vehicle is deleted, archived, or FLS-stripped.

VehiclePreviewDto

Read-only preview of the referenced canonical Vehicle. All fields nullable. May be null when the underlying Vehicle is unavailable.
plate
​string | null
plateState
​string | null

Plate issuing-state code (e.g. CA).

make
​string | null
model
​string | null
year
​string | null

Vehicle model year, carried as a string.

color
​string | null

CaseItemDto

One case-item link on a theft case, carried in the `caseItems` array. The case item stores the SKU the incident reported in `sku`, and may also link a canonical Item through `itemId`; the link never replaces what was reported. `sku` and `itemId` are optional but encouraged, and a case item needs at least one reported detail (`sku`, `itemId`, `notes`, `quantity`, `valueAtIncident`, `category`, `upc`, `serialNumber`, `unitType`, `condition`, `itemName`, `merchandiseCategory`, `merchandiseType`, `brand`, `department`, `stockNumber` or `unitCost`); cash, for example, carries neither. itemPreview carries the linked Item's own name, SKU and category on reads, and the API ignores it on writes. A null itemPreview on the response means no Item is linked, or signals graceful degradation when the underlying Item is deleted, archived, or FLS-stripped.
id
​string | null · salesforce-id

Salesforce record id of the Case_Item__c junction row, assigned by Salesforce on insert. Null on POST cascade entry (new junction). Differs from involvementId, which the caller mints.

involvementId
​string | null · maxLength: 36

Caller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. At most 36 characters for a new or changed value; a value already stored on the case item is accepted unchanged whatever its length, and returned on every read. Immutable after create: an update that sends a different value for a stored involvement returns 400 IMMUTABLE_FIELD; a value that differs only in case is the same value, and the stored spelling is kept. A value already held by another involvement, on this case or any other, or repeated inside one request, returns 409 DUPLICATE_INVOLVEMENT_ID; the comparison ignores case.

itemId
​string · salesforce-id

Canonical Item id. Optional: on a new case item a sku that matches exactly one Item sets it for you; a stored case item is never linked by SKU. An id that names no Item returns 422 NATURAL_KEY_NOT_FOUND, and on a new case item an id and a sku that name different Items return 400 INVARIANT_VIOLATION. Immutable after create.

sku
​string | null · maxLength: 80

SKU as the incident reported it, stored as sent. Optional but encouraged. Matched against the Item catalog exactly after trimming and ignoring case, on SKU only and not UPC; on a new case item one match links that Item, no match or several leave the row unlinked, and a stored case item is never matched.

quantity
​number | null

Quantity of items involved in the incident.

condition
​string | null

Recovery Status of the item: recovered, damaged or not recovered. Open-set: the org stores the value its value mapping gives each, and a value no row maps is stored and read back as sent.

valueAtIncident
​number | null

Assessed value of the item at the time of the incident.

category
​string | null

Item category (e.g. Electronics, Apparel, Grocery). Open-set — not enumerated.

notes
​string | null

Case-side mutable context for the junction.

upc
​string | null

Universal Product Code for the involved item.

serialNumber
​string | null

Serial number of the involved item.

unitType
​string | null

Unit type of the involved item (e.g. Each, Pair, Case).

itemName
​string | null

Name of the item as the incident reported it. Stored on the case item as sent.

merchandiseCategory
​string | null

Merchandise category as reported. Any text is accepted, subject to any restriction the org places on the picklist.

merchandiseType
​string | null

Merchandise type as reported. Any text is accepted, subject to any restriction the org places on the picklist.

brand
​string | null

Brand as reported, free text.

department
​string | null

Department the item belongs to, as stored. Open-set: not enumerated.

stockNumber
​string | null

Stock number the retailer assigns the item, stored as sent.

unitCost
​number | null

Cost of one unit to the retailer.

totalPrice
​number | null · readOnly

Total price of the line, calculated by the platform. Returned on a load and ignored on writes.

totalCost
​number | null · readOnly

Total cost of the line, calculated by the platform. Returned on a load and ignored on writes.

attributedTo
​string | null · salesforce-id

Salesforce id of a saved involved person on this case that the item is attributed to. To name a person reported in the same request, send attributedToInvolvementId instead. An id that is not an involved person on this case is refused with 400 INVARIANT_VIOLATION. Removing the attributed person from the case, by detaching it or by a PUT that leaves it out and omits caseItems, clears the attribution. To change or clear an attribution, change or clear both attributedTo and attributedToInvolvementId: clearing only attributedTo while sending the loaded attributedToInvolvementId keeps the attribution.

attributedToInvolvementId
​string | null

The involvementId of the involved person the item is attributed to, whether that person is in the same request or already on the case. It is resolved to attributedTo when the case is saved, in the same all-or-nothing save as the persons. A value that no involved person on this case holds is refused with 400 INVARIANT_VIOLATION. When attributedTo is also sent, both must name the same person or the request is refused with 400 INVARIANT_VIOLATION. A loaded case returns both attributedTo and attributedToInvolvementId for an attributed item. To change or clear an attribution, change or clear both fields: clearing only attributedTo while sending the loaded attributedToInvolvementId keeps the attribution, and repointing attributedTo while sending the old attributedToInvolvementId is refused.

​ItemPreviewDto | null · readOnly

Read-only preview of the referenced Item. Returned as null when the underlying Item is deleted, archived, or FLS-stripped.

ItemPreviewDto

Read-only preview of the referenced canonical Item. All fields nullable. May be null when the underlying Item is unavailable.
name
​string | null

Item display name.

sku
​string | null

Stock-keeping unit identifier.

category
​string | null

Item category.

FieldSpec

Per-field metadata for form rendering. One shared shape across all domains. Each domain populates the keys it has, and leaves the rest null.
name
​string

Domain property name (e.g. narrative).

label
​string

Display label.

type
​string

Field type (e.g. string, boolean, date, picklist, reference).

required
​boolean | null
readOnly
​boolean | null

Populated by theft and person. Null for vehicle, item, and location.

createable
​boolean | null

Populated by vehicle, item, and location. Null for theft and person.

updateable
​boolean | null

Populated by vehicle, item, and location. Null for theft and person.

section
​string | null
referenceTo
​string | null

For reference fields, the related SObject API name.

​array | null

Structured picklist options.

​array | null

Dependent-picklist option sets keyed by controlling value (theft only).

controllingFieldName
​string | null
layoutHint
​string | null

FieldSpecOption

One choice for a picklist or suggested-value field. `label` equals `value`. `value` is the org value to send and store. `key` is the domain key the value belongs to, null when it belongs to none.
label
​string

Display label. Equal to value.

value
​string

The org value to send for the field. For an Incident Type it is the value to send as incidentType.

key
​string | null

The domain key the value belongs to. Several values may share one key, such as Robbery-Armed and Robbery-Unarmed for robbery. Null when the value maps to no key, and on options listed from a picklist field no value mapping row covers.

FieldSpecControlledOption

value
​string

Controlling field value this option set applies to.

TheftEnvelope

Response envelope for theft case operations
​TheftDto · required

The theft case body.

​FieldSpec[] · required

Field specifications for the case's classification context, including the incidentTypeKey picklist described on /theft-cases/field-specs

derivedKeys
​string[] · required

Keys of detail derived from another field (incidentTypeKey from incidentType, locationNumber from primaryLocationId). A client that sends detail back on a PUT leaves them out, so a stale copy cannot contradict an edit to the field it was derived from.

Example: ["incidentTypeKey","locationNumber"]

CustomPropertySpec

One tenant-owned case field. `key` is the domain property key.
key
​string · required

Domain property key. Never a Salesforce field API name.

label
​string · required

Mapping label, or the field label when the mapping label is blank.

type
​string · required

Field type from the describe, using the same words as fieldSpecs.

required
​boolean · required

True when POST /theft-cases must send a value.

Picklist options from the field describe, when the field has them.

StandardError

Standard error response shape returned by all paths
code
​string · enum · required

Machine-readable error code

Enum values:
BAD_REQUEST
FLS_DENIED
INVARIANT_VIOLATION
INVALID_TRANSITION
IMMUTABLE_FIELD
CUSTOM_PROPERTY_NOT_DEFINED
CUSTOM_PROPERTY_REQUIRED
CUSTOM_PROPERTY_NOT_WRITABLE
message
​string · required

Human-readable error message

id
​string · salesforce-id

Present with DUPLICATE_UUID on a POST: the id of the case that already holds the uuid

field
​string

Present with NATURAL_KEY_NOT_FOUND, NATURAL_KEY_AMBIGUOUS, INCIDENT_TYPE_NOT_MAPPED and the CUSTOM_PROPERTY_* codes: the request field whose value did not resolve (locationNumber, employeeNumber, employeeId, externalId, personId, vehicleId, vin, plate, itemId, sku or incidentTypeKey), or the custom property key that failed. Custom property refusals do not include value.

value
​string

Present with NATURAL_KEY_NOT_FOUND and NATURAL_KEY_AMBIGUOUS: the value that did not resolve, as the caller sent it

ids
​string[]

Present with NATURAL_KEY_AMBIGUOUS: the ids of the records the key matches, for Salesforce-side callers. A caller outside Salesforce settles the ambiguity with a more specific natural key.