Create, retrieve, and update theft cases.
Load a Theft Case with field metadata
Returns the { detail, fieldSpecs } envelope. detail holds the case, and fieldSpecs describes its fields for the classification context. Name the case by exactly one of id or uuid: sending both, or neither, returns 400 BAD_REQUEST. uuid is matched in lower case and in upper case, so a value in any letter case finds a case stored in either spelling, including one stored in upper case before uuids were lower-cased. Known gap: a uuid stored in mixed letter case is not found. More than one match returns 409 AMBIGUOUS_UUID; a case is never picked. An org whose active mapping carries no uuid column returns 400 INVARIANT_VIOLATION for a uuid lookup. A uuid or id that no case carries returns 404 NOT_FOUND. detail.reportedAt is the record's creation time and is read-only. detail.locationNumber is the Location Number of the primary location, the location's unique external id. To get field specifications without a case, use /theft-cases/field-specs.
query Parameters
idSalesforce Investigation record Id. Send exactly one of id or uuid.
15- or 18-character Salesforce record Id for ThinkLP__Investigation__c
uuidThe case's external uuid, in any letter case. Send exactly one of id or uuid.
The uuid the case was created with; new cases store it in lower case
Load a Theft Case with field metadata › Responses
The envelope, with the case in detail and its field specifications in fieldSpecs.
The theft case body.
Field specifications for the case's classification context, including the incidentTypeKey picklist described on /theft-cases/field-specs
derivedKeysKeys 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.
Update an existing Theft Case
Updates an existing theft case from the supplied body. Returns the { detail, fieldSpecs } envelope. The id query parameter is authoritative. If the body also carries an id, the two values must match, or the API returns 400 BAD_REQUEST.
The primary location may be named by primaryLocationId or by locationNumber, and an involved employee by employeeId or employeeNumber. The incident type may be named by incidentTypeKey, which the package stores as the org value it maps to; see the incidentTypeKey property. Sending both forms of a key with different values returns 400 INVARIANT_VIOLATION. A number, or an employeeId, personId, itemId or vehicleId, that names no record returns 422 NATURAL_KEY_NOT_FOUND with the field and value that failed. An involved person's externalId is never resolved to a Person; link by natural key through the link routes. Sending a different personId for an involved person the case already stores returns 400 IMMUTABLE_FIELD; change the Person through PUT /theft-cases/{caseId}/involved-persons/link. A currencyIsoCode the org cannot hold returns 422 CURRENCY_NOT_SUPPORTED and writes nothing. reportedAt is read-only. reportedAt, locationNumber and currencyIsoCode are returned on every response, and a locationNumber sent back with the primaryLocationId it was read with names the same location.
The body is the whole document. A field the body omits, or sends as null, is cleared on the stored case. The exceptions keep their stored value: uuid, which is immutable, closedDateTime, which survives a reopen, the read-only fields, and any field the org requires, such as currencyIsoCode in a multi-currency org. An omitted status is not kept: the case is saved as Open, so a PUT without status reopens a closed case. An omitted child list keeps the stored rows, and an empty list removes them.
The update is written all or nothing. If anything fails after the first write, including provisioning a Person for an employee, every row written so far is rolled back before the error is returned.
query Parameters
idSalesforce Investigation record Id of the case to update
15- or 18-character Salesforce record Id
Update an existing Theft Case › Request Body
idSalesforce Investigation record Id
investigationTypeInvestigation type picklist value (e.g. External Theft, Internal Theft). Immutable after create.
incidentDateDate of the incident (YYYY-MM-DD)
incidentTimeTime of the incident as string (HH:MM)
primaryLocationIdSalesforce Id of the primary location record. Send this or locationNumber; if both are sent they must name the same location.
locationNumberLocation 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.
reportedAtWhen 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.
statusCase status picklist value (Open, Closed, Pending Assignment, Pending Approval)
incidentTypeThe 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.
incidentTypeKeyThe 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).
incidentTypeLabelWrite only, ignored on a response. The value to store when incidentTypeKey has no mapping in the org.
methodPrimaryPrimary theft method picklist value
methodSecondarySecondary theft method picklist value
narrativeFree-text narrative description of the incident.
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.
initialCaseValueInitial estimated value of the case. Immutable after create.
currencyIsoCodeISO 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.
totalCaseValueTotal calculated value of all stolen items (read-only rollup)
totalItemsTotal number of items involved in the case (read-only rollup)
totalCaseValueRecoveredTotal value recovered (read-only rollup)
uuidExternal 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.
investigatorIdSalesforce User Id of the assigned investigator
priorityCase priority picklist value, as stored. Open-set: not enumerated. Omitting it on an update keeps the stored value.
outcomeCase outcome picklist value, as stored. Open-set: not enumerated. Omitting it on an update keeps the stored value.
caseReportCase report, as rich text (HTML). Omitting it on an update keeps the stored value.
executiveSummaryExecutive summary, as rich text (HTML). Omitting it on an update keeps the stored value.
investigationPlanInvestigation plan, as rich text (HTML). Omitting it on an update keeps the stored value.
promissoryAmountPromissory note amount
damagesDamages picklist value
damageDescriptionFree-text description of damages
actionsTakenActions taken during the incident
preventativeActionsPreventative actions recommended
policeNotifiedYes/No picklist indicating if police were notified
policeNotifiedTimeDatetime when police were notified (ISO 8601)
policeArrivalTimeDatetime when police arrived (ISO 8601)
policeDepartmentName of the police department
policeOfficerNameName of the responding police officer
policeOfficerBadgeNumberBadge number of the responding police officer
policeReportNumberPolice report number
policeDispositionPolice disposition picklist value
concealmentLocationLocation where items were concealed
concealmentMethodHow the items were concealed, as reported. Any text is accepted.
pointOfEntryHow the offender got into the location, free text up to 100 characters. Accepted on any Investigation Type.
reportDateDate the incident was reported
reportTimeTime the incident was reported (HH:mm:ss)
closedDateTimeDate/time the case was closed (read-only)
incidentNumberAuto-generated incident number (read-only)
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.
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.
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.
Update an existing Theft Case › Responses
OK. The response body is the { detail, fieldSpecs } envelope, reflecting the saved case.
The theft case body.
Field specifications for the case's classification context, including the incidentTypeKey picklist described on /theft-cases/field-specs
derivedKeysKeys 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.
Create a new Theft Case
Creates a theft case from the supplied body. This endpoint only creates, so do not include an id field. A body that carries one returns 400 BAD_REQUEST.
Supply investigationType. Name the incident type by incidentTypeKey, with incidentTypeLabel as the value to store when the org maps the key to none; see the incidentTypeKey property. Any other field you leave null takes a default, so status becomes Open and incidentDate becomes today.
A uuid is unique across cases. Send a uuid you mint and reuse it on retry: a request that repeats the uuid of a stored case writes nothing, ignores the new body and returns 409 DUPLICATE_UUID with the stored case's id. Treat that 409 and its id as the first call having landed; use GET ?uuid= to read the case and PUT to change it. A new uuid is stored in lower case and looked up in lower and upper case, so a repeat that differs only in letter case names the same case. A case whose uuid was stored in mixed letter case is not found and would be created again (known gap). Two requests racing on one uuid resolve the same way: the loser writes nothing and returns 409 DUPLICATE_UUID with the winner's id. A new case returns 200 with its envelope.
The report is written all or nothing. If anything fails after the first write, including provisioning a Person for an employee, every row written so far is rolled back before the error is returned.
Name the primary location by primaryLocationId or locationNumber, and an involved employee by employeeId or employeeNumber. Each kind of number resolves in one call however many involved persons name one, and the employees' Persons are found or created in one call. Sending both forms of a key with different values returns 400 INVARIANT_VIOLATION. A number, or an employeeId, personId, itemId or vehicleId, that names no record returns 422 NATURAL_KEY_NOT_FOUND with the field and value that failed. A case item's sku links the one Item it matches and otherwise is stored unlinked, and a reported plate or VIN never links a Vehicle. A case is taken in by linking only through a Salesforce id (personId, vehicleId, itemId), through an employeeId and through an exact sku match; an involved person's externalId is never resolved to a Person. To link a stored involvement by any other natural key, use the link routes. Reported details such as names, descriptions, plates and SKUs never cause a 422. A currencyIsoCode the org cannot hold returns 422 CURRENCY_NOT_SUPPORTED and writes nothing: a single-currency org holds only its own currency, and a multi-currency org holds its active currencies. Omit the field to keep the default.
Create a new Theft Case › Request Body
idSalesforce Investigation record Id
investigationTypeInvestigation type picklist value (e.g. External Theft, Internal Theft). Immutable after create.
incidentDateDate of the incident (YYYY-MM-DD)
incidentTimeTime of the incident as string (HH:MM)
primaryLocationIdSalesforce Id of the primary location record. Send this or locationNumber; if both are sent they must name the same location.
locationNumberLocation 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.
reportedAtWhen 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.
statusCase status picklist value (Open, Closed, Pending Assignment, Pending Approval)
incidentTypeThe 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.
incidentTypeKeyThe 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).
incidentTypeLabelWrite only, ignored on a response. The value to store when incidentTypeKey has no mapping in the org.
methodPrimaryPrimary theft method picklist value
methodSecondarySecondary theft method picklist value
narrativeFree-text narrative description of the incident.
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.
initialCaseValueInitial estimated value of the case. Immutable after create.
currencyIsoCodeISO 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.
totalCaseValueTotal calculated value of all stolen items (read-only rollup)
totalItemsTotal number of items involved in the case (read-only rollup)
totalCaseValueRecoveredTotal value recovered (read-only rollup)
uuidExternal 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.
investigatorIdSalesforce User Id of the assigned investigator
priorityCase priority picklist value, as stored. Open-set: not enumerated. Omitting it on an update keeps the stored value.
outcomeCase outcome picklist value, as stored. Open-set: not enumerated. Omitting it on an update keeps the stored value.
caseReportCase report, as rich text (HTML). Omitting it on an update keeps the stored value.
executiveSummaryExecutive summary, as rich text (HTML). Omitting it on an update keeps the stored value.
investigationPlanInvestigation plan, as rich text (HTML). Omitting it on an update keeps the stored value.
promissoryAmountPromissory note amount
damagesDamages picklist value
damageDescriptionFree-text description of damages
actionsTakenActions taken during the incident
preventativeActionsPreventative actions recommended
policeNotifiedYes/No picklist indicating if police were notified
policeNotifiedTimeDatetime when police were notified (ISO 8601)
policeArrivalTimeDatetime when police arrived (ISO 8601)
policeDepartmentName of the police department
policeOfficerNameName of the responding police officer
policeOfficerBadgeNumberBadge number of the responding police officer
policeReportNumberPolice report number
policeDispositionPolice disposition picklist value
concealmentLocationLocation where items were concealed
concealmentMethodHow the items were concealed, as reported. Any text is accepted.
pointOfEntryHow the offender got into the location, free text up to 100 characters. Accepted on any Investigation Type.
reportDateDate the incident was reported
reportTimeTime the incident was reported (HH:mm:ss)
closedDateTimeDate/time the case was closed (read-only)
incidentNumberAuto-generated incident number (read-only)
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.
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.
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.
Create a new Theft Case › Responses
OK. The response body is the { detail, fieldSpecs } envelope. detail carries the saved case, with its platform-assigned id populated.
The theft case body.
Field specifications for the case's classification context, including the incidentTypeKey picklist described on /theft-cases/field-specs
derivedKeysKeys 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.
Load the case field contract without a Theft Case
Returns the same fieldSpecs array that the /theft-cases envelope carries. No case id is required, so you can build a form before any case exists. The specs describe the case detail contract. In a FALLBACK org, the specs are the packaged catalog. In a MAPPED org, the API derives the specs from the org's active property mappings, so labels and picklist options reflect the subscriber's configuration. spec.name is always the canonical domain property, never the subscriber's field API name. Every response also carries an incidentTypeKey picklist: one option per domain Incident Type key the org maps, with the key as value and the org value that key stores as label. Send the chosen value as incidentTypeKey.
The options of Incident Type, Theft Method (primary and secondary), concealment method and location, Priority, Outcome and Police Disposition come from the org's value mapping: each option's label equals its value, its key is the domain key the value belongs to, and a value the org added appears with the packaged ones. A property the org maps no values for lists the values of its picklist field. Options are not checked against the org's field: a mapped value the org's restricted picklist does not list is still offered, and saving it is refused, so the fix is the org's value mapping. Incident Type carries controllingFieldName investigationType and a controlledOptions set for each Investigation Type: a packaged Incident Type that does not apply to the Investigation Type is left out, and so is a mapped value made for the other one. Outcome applies to Internal cases only, so it is a controlledPicklist with an option set for Internal alone. In a MAPPED org, each Investigation Type option carries the API value a write accepts (External Theft or Internal Theft) as its value and the org's value for that type as its label; the Incident Type and Outcome option sets are keyed by those API values.
Load the case field contract without a Theft Case › Responses
Field specifications for the case detail contract.
Tenant-owned case fields, in form order. Empty when the org has none. fieldSpecs is unchanged.