ThinkLP
TheftCase API

Case Items

Serverhttps://yourorg.my.salesforce.com/services/apexrest/ThinkSDK/thinklp/api/v1

Attach and detach the items involved in a case.


Attach an item to a Theft Case

POST
https://yourorg.my.salesforce.com/services/apexrest/ThinkSDK/thinklp/api/v1
/theft-cases/{caseId}/case-items

Stores the item as the incident reported it: sku, quantity and any other reported detail are written to the case item itself, and no canonical Item is ever created. 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), so cash can be attached with neither. A body with no reported detail returns 400 INVARIANT_VIOLATION. A sku matches exactly after trimming and ignoring case, on SKU only and not UPC, and links the Item only when it matches exactly one. A SKU that matches no Item, or more than one, is stored unlinked and the request still returns 201. An id in the body is ignored: the request always adds a new case item. An itemId that names no Item returns 422 NATURAL_KEY_NOT_FOUND with the field and value that failed, and an itemId and a sku that name different Items return 400 INVARIANT_VIOLATION. involvementId is the caller-minted identifier of the involvement, and the attach is idempotent on it: repeating an attach whose involvementId is already stored on this case writes nothing and returns 200 with the stored involvement and replayed: true, and the rest of the repeated body is ignored. An involvementId already stored on another case returns 409 DUPLICATE_INVOLVEMENT_ID, and an uuid carried by more than one case returns 409 AMBIGUOUS_UUID. The change is written all or nothing; if any write fails, every row written so far is rolled back. The response body is read back after the write commits; if that read fails the request returns 500 although the attach was written, and repeating the attach returns the stored involvement.

Attach an item to a Theft Case › path Parameters

caseId
​string · required

Salesforce Investigation record Id of the parent theft case, or the uuid of the Incident it was reported from. An Incident uuid names the Theft Case that Incident is in. A value that is neither returns 400 BAD_REQUEST, and one that names no case returns 404 NOT_FOUND. An uuid carried by more than one case returns 409 AMBIGUOUS_UUID, and an org whose active mapping carries no uuid column returns 400 INVARIANT_VIOLATION for an uuid.

Attach an item to a Theft Case › Request Body

sku
​string · maxLength: 80

Stock-keeping unit identifier as reported. Optional but encouraged.

quantity
​number | null

Quantity of items involved in the incident.

itemId
​string | null · salesforce-id

Existing canonical Item to link. Must name the same Item the SKU matches, when it matches one.

involvementId
​string | null · maxLength: 36

Caller-minted identifier of this involvement, reused unchanged on retry. At most 36 characters for a new value. Immutable after create.

condition
​string | null

Recovery Status of the item: recovered, damaged or not recovered. The org stores the value its value mapping gives each; 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.

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.

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. Open-set: not enumerated.

stockNumber
​string | null

Stock number the retailer assigns the item.

unitCost
​number | null

Cost of one unit to the retailer.

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.

notes
​string | null

Case-side context notes for the new junction.

Attach an item to a Theft Case › Responses

OK — the involvementId was already stored on this case. The stored involvement is returned with replayed: true and nothing was written.

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.
replayed
​boolean · enum · required

Always true: the attach was a repeat and wrote nothing.

Enum values:
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.


Detach case items from a Theft Case

DELETE
https://yourorg.my.salesforce.com/services/apexrest/ThinkSDK/thinklp/api/v1
/theft-cases/{caseId}/case-items

Detaches the case items named by involvementIds, the caller-minted ids, or by ids, the involvement row ids, without deleting the canonical Item records. Sending both, or neither, returns 400 BAD_REQUEST. An id that does not belong to the case surfaces as 404 NOT_FOUND. The change is written all or nothing; if any write fails, every row written so far is rolled back. The case is loaded first, so the caller needs read access to it, and a failure reading it or a record it links to returns that error before anything is removed.

Detach case items from a Theft Case › path Parameters

caseId
​string · required

Salesforce Investigation record Id of the parent theft case, or the uuid of the Incident it was reported from. An Incident uuid names the Theft Case that Incident is in. A value that is neither returns 400 BAD_REQUEST, and one that names no case returns 404 NOT_FOUND. An uuid carried by more than one case returns 409 AMBIGUOUS_UUID, and an org whose active mapping carries no uuid column returns 400 INVARIANT_VIOLATION for an uuid.

Detach case items from a Theft Case › query Parameters

involvementIds
​string

Comma-separated caller-minted involvementId values of the involvements to detach, compared without regard to case. Send either involvementIds or ids, not both. An id that is not on the case returns 404 NOT_FOUND and nothing is removed.

ids
​string

Comma-separated CaseItemId values. Send either ids or involvementIds, not both.

Detach case items from a Theft Case › Responses

No Content — junctions detached.

No data returned

PUT
https://yourorg.my.salesforce.com/services/apexrest/ThinkSDK/thinklp/api/v1
/theft-cases/{caseId}/case-items/link

Links a stored case item to an existing canonical Item, named by itemId or by sku, and returns the updated case item. caseId in the path is a Salesforce id or an Incident uuid. Linking never creates a canonical record and never changes one, and the reported details on the case item are kept as they are. Linking a case item to the record it already names writes nothing. A key that names no record returns 422 NATURAL_KEY_NOT_FOUND with the field and value that failed. A sku that matches several Items is reported by Foundation's lookup as matching none, so it too returns 422 NATURAL_KEY_NOT_FOUND, never NATURAL_KEY_AMBIGUOUS; the packaged SKU field is unique, so this arises only in a Mapped org. Send no key, or both itemId and sku, and the request returns 400 INVARIANT_VIOLATION. A caseId that names nothing, or an involvementId the case does not hold, returns 404 NOT_FOUND. The change is written all or nothing.

caseId
​string · required

Salesforce Investigation record Id of the parent theft case, or the uuid of the Incident it was reported from. An Incident uuid names the Theft Case that Incident is in. A value that is neither returns 400 BAD_REQUEST, and one that names no case returns 404 NOT_FOUND. An uuid carried by more than one case returns 409 AMBIGUOUS_UUID, and an org whose active mapping carries no uuid column returns 400 INVARIANT_VIOLATION for an uuid.

involvementId
​string · required

The caller-minted identifier of the stored case item on this case, compared without regard to case. It names the case item to link; a value the case does not hold returns 404 NOT_FOUND.

itemId
​string · salesforce-id

Salesforce id of the canonical Item to link.

sku
​string

SKU of the canonical Item to link, matched ignoring case and surrounding spaces. Foundation's SKU lookup reports a SKU that matches several Items as matching none, so an ambiguous SKU returns 422 NATURAL_KEY_NOT_FOUND, never NATURAL_KEY_AMBIGUOUS. The packaged SKU field is unique, so this arises only in a Mapped org.

replace
​boolean

Set true to replace a different record the case item already names. Without it, a case item already linked to a different record returns 409 ALREADY_LINKED.

Default: false
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: itemId
type = object · requires: sku
Properties for Variant 1:
itemId
​string · salesforce-id · required

Salesforce id of the canonical Item to link.

involvementId
​string

The caller-minted identifier of the stored case item on this case, compared without regard to case. It names the case item to link; a value the case does not hold returns 404 NOT_FOUND.

sku
​string

SKU of the canonical Item to link, matched ignoring case and surrounding spaces. Foundation's SKU lookup reports a SKU that matches several Items as matching none, so an ambiguous SKU returns 422 NATURAL_KEY_NOT_FOUND, never NATURAL_KEY_AMBIGUOUS. The packaged SKU field is unique, so this arises only in a Mapped org.

replace
​boolean

Set true to replace a different record the case item already names. Without it, a case item already linked to a different record returns 409 ALREADY_LINKED.

Default: false

OK — the updated case item. Linking to the record the case item already names returns 200 and changes nothing.

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.