Incidents
Report Loss Prevention incidents and read them back with a partner API key.
Find an incident by the source system and id it was reported under
Needs the cases.incident-writer or cases.incident-reader scope. Use it to find an incident when you hold the source system and id but not the incident id. A reference that is still being filed answers 404 INCIDENT_NOT_FOUND.
query Parameters
external_source^[a-z][a-z0-9_-]{1,3… · requiredThe system the Incident came from, as a lowercase slug of 2 to 32 characters that starts with a letter and holds letters, digits, _ or -, for example safr.
external_idThe Incident's id in that system. A source and id name one Incident in a tenant, so a second report with the same source and id creates nothing and answers 200 with the first Incident.
Find an incident by the source system and id it was reported under › Responses
The incident.
Report a Loss Prevention incident
Needs the cases.incident-writer scope, and an integration user whose team role grants the permission to report incidents. You create the incident id as a UUID and reuse it on every retry. When you send an external_reference, a second report with the same source and id creates nothing and answers 200 with the first incident; a report made while the first is still being filed gets 409 EXTERNAL_REFERENCE_IN_FLIGHT with a Retry-After header, so retry it.
Headers
Idempotency-KeyA UUID that makes a retry safe. A retry with the same key and the same request replays the first answer; the same key with a different request (method, route, path parameters or body) gets 409 IDEMPOTENCY_KEY_REUSED_DIFFERENT_BODY, and a retry while the first request is still running gets 409 IDEMPOTENCY_KEY_IN_FLIGHT. A key that is not a UUID gets 400 IDEMPOTENCY_KEY_INVALID. Keys expire after 24 hours.
Report a Loss Prevention incident › Request Body
categoryThe Incident category. It selects the Loss Prevention shape.
When the Incident happened, local to the location. A date and, when known, a time of day.
location_numberThe Location Number the business uses. It resolves to one location. A leading apostrophe or dropped leading zeros still match. A report with an apprehension needs the exact Location Number.
idThe Incident id. The caller mints this UUID and reuses it on every retry, so a retry names the same Incident.
offender_typeWho committed the Incident. Omit it when unknown, and then any listed Incident Type is valid. The deprecated value both also means unknown. The Salesforce system of record refuses an Incident with no Offender Type with 422 INCIDENT_NOT_SUPPORTED_BY_SYSTEM_OF_RECORD.
incident_typeThe kind of Incident, as a key from GET /v1/incidents/options. Keys are the same for every tenant, but clients read them from the options and do not hard-code them. A key that does not apply to the Offender Type gets 422 INCIDENT_TYPE_NOT_ALLOWED. When the Offender Type is unknown, any listed key is valid. Omit it when unknown.
narrativeThe free-text account of the Incident. Omit it when there is none.
The estimated loss from the Incident. Omit it when unknown.
How the theft happened: a primary Theft Method and an optional secondary. An unknown key, a missing primary, or a secondary equal to the primary gets 422 INCIDENT_RULE_VIOLATED with rule theft_method_not_allowed. Omit it when unknown. A stored method that has no key is left out on load.
concealment_deviceThe device used to conceal the goods, as a key from concealment_devices in GET /v1/incidents/options. An unknown key gets 422 INCIDENT_RULE_VIOLATED with rule concealment_device_not_allowed. Omit it when unknown.
register_number^[^\p{Cc}\p{Cf}]*$The register the goods passed, under the domain key register_number from the tenant case mapping. A blank value is left out. This is never a Salesforce field name. A value longer than 80 characters, or with a control or invisible format character such as a zero-width joiner, is a bad request. The refusal is on purpose: an invisible character must not make a blank value count as a register number. A mapping that does not define the key gets 422 INCIDENT_RULE_VIOLATED with rule register_number_not_defined. A mapping that requires it, when the report leaves it out, gets rule register_number_required. A value the org cannot store gets 422 INCIDENT_NOT_SUPPORTED_BY_SYSTEM_OF_RECORD with reason register_number.
entry_pointHow the offender got in, in free text of at most 100 characters, such as a door or a window. Any Incident can have one. A blank value is left out. A longer value gets 422 INCIDENT_RULE_VIOLATED with rule invalid_field. Weapon and injury detail goes in the narrative. Omit it when unknown.
The Law Enforcement Detail: whether the police were called and, when they were, the facts about the call. A load returns it whenever the answer was recorded.
The people involved in the Incident, at most 100.
The items involved in the Incident, at most 100.
The vehicles involved in the Incident, at most 100.
The system this Incident came from and its id there. A second report with the same source and id answers 200 with the first Incident and creates no second one. A report made while the first is still being filed gets 409 EXTERNAL_REFERENCE_IN_FLIGHT with Retry-After; retry it. Omit it for an Incident made here.
The values of the tenant's customer fields. Each key is the domain property key from the tenant case mapping, as customer_fields[].key in GET /v1/incidents/options names it, and never a Salesforce field name. Each value is text. Values are trimmed, and a blank value is left out. A key that does not match ^[A-Za-z][A-Za-z0-9_]{0,79}$, the key register_number, a value longer than 32768 characters, or more than 50 entries gets 422 INCIDENT_RULE_VIOLATED with rule invalid_field and field customer_fields. A key the mapping does not define gets rule customer_field_not_defined, and a required field left out gets rule customer_field_required, both with field customer_fields. A value the org cannot store gets 422 INCIDENT_NOT_SUPPORTED_BY_SYSTEM_OF_RECORD with reason customer_field. After any of those three refusals, read the options again. An API instance remembers the fields for up to 5 minutes, so that read can still return the old list for a while.
Report a Loss Prevention incident › Responses
The external_reference names an incident that was already reported, so nothing was created and the response names the first incident.
The result of reporting an Incident.
List the values a report accepts
Needs the cases.incident-writer or cases.incident-reader scope. Returns the valid incident types for each offender type, the roles, theft methods, concealment devices, license states and item categories. Read the keys here and do not hard-code them.
query Parameters
categoryThe incident category. A key can ask for loss_prevention only.
List the values a report accepts › Responses
The valid values.
The values POST /v1/incidents validates against: the valid Incident Types (key and label) for each Offender Type, the Roles, the Theft Methods, the Concealment Devices, the license states, the item categories, and the tenant's customer fields.
Read an incident
Needs the cases.incident-writer or cases.incident-reader scope. The external_reference is the source system and id the incident was reported under, or null.
path Parameters
idThe id of the Incident to load.
Read an incident › Responses
The incident.