ThinkLP
ThinkLP API

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

GET
/v1/incidents

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.

Find an incident by the source system and id it was reported under › query Parameters

external_source
​string · pattern: ^[a-z][a-z0-9_-]{1,3… · required

The 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_id
​string · minLength: 1 · maxLength: 200 · required

The 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.

​Incident · required

Report a Loss Prevention incident

POST
/v1/incidents

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.

Report a Loss Prevention incident › Headers

Idempotency-Key
​string · uuid

A 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

category
​string · const · required

The Incident category. It selects the Loss Prevention shape.

Const value: loss_prevention
​object · required

When the Incident happened, local to the location. A date and, when known, a time of day.

location_number
​string · minLength: 1 · required

The 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.

id
​string · uuid · required

The Incident id. The caller mints this UUID and reuses it on every retry, so a retry names the same Incident.

offender_type
​string · enum

Who 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.

Enum values:
internal
external
both
incident_type
​string · minLength: 1

The 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.

narrative
​string · minLength: 1

The free-text account of the Incident. Omit it when there is none.

​object

The estimated loss from the Incident. Omit it when unknown.

​object

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_device
​string · minLength: 1 · maxLength: 64

The 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
​string · maxLength: 80 · pattern: ^[^\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_point
​string

How 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.

​object

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.

​object[] · maxItems: 100

The people involved in the Incident, at most 100.

Default: []
​object[] · maxItems: 100

The items involved in the Incident, at most 100.

Default: []
​object[] · maxItems: 100

The vehicles involved in the Incident, at most 100.

Default: []
​object

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.

​object

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.

​ReportIncidentResult · required

The result of reporting an Incident.


List the values a report accepts

GET
/v1/incidents/options

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.

List the values a report accepts › query Parameters

category
​string · enum · required

The incident category. A key can ask for loss_prevention only.

Enum values:
loss_prevention

List the values a report accepts › Responses

The valid values.

​IncidentOptions · required

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

GET
/v1/incidents/{id}

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.

Read an incident › path Parameters

id
​string · uuid · required

The id of the Incident to load.

Read an incident › Responses

The incident.

​Incident · required