Cases — List Cases

Method/Path: GET /incidents
Summary: List Cases
Operation ID: listIncidents
Auth: bearerAuth (OAuth 2.0)

Description:

Retrieve cases with optional filtering (AND logic across all filters).

Date Filters (ISO 8601, open-ended ranges supported):

lastModifiedDateFrom / lastModifiedDateTo - Filter by LastModifiedDate
createdDateFrom / createdDateTo - Filter by CreatedDate
Formats: YYYY-MM-DD (date only) or YYYY-MM-DDTHH:mm:ssZ (full datetime)
Open-ended: Can specify only 'from' or only 'to' (or both)

Text Filters (exact match, case-sensitive):

incidentType - Incident type (e.g., "Theft", "Fraud")
investigationType - Investigation type (e.g., "External Theft")
status - Case status (e.g., "Open", "Closed")

Filter Combination: All filters are optional and combined with AND logic.

Example:

?lastModifiedDateFrom=2025-10-01&status=Open&incidentType=Theft

Returns all Theft incidents with Open status modified on/after Oct 1, 2025.

Parameters

Name	In	Type	Required	Description	Notes
`API-Version`	header	string	✅ Yes	API version	Default: `1.0`
`lastModifiedDateFrom`	query	string (date-time)	❌ No	Filter by LastModifiedDate >= (ISO 8601)	Example: `2025-10-01` or `2025-10-01T00:00:00Z`
`lastModifiedDateTo`	query	string (date-time)	❌ No	Filter by LastModifiedDate <= (ISO 8601)	-
`createdDateFrom`	query	string (date-time)	❌ No	Filter by CreatedDate >= (ISO 8601)	-
`createdDateTo`	query	string (date-time)	❌ No	Filter by CreatedDate <= (ISO 8601)	-
`incidentType`	query	string	❌ No	Exact match incident type (case-sensitive)	Examples: `Theft`, `Fraud`
`investigationType`	query	string	❌ No	Exact match investigation type (case-sensitive)	Examples: `External Theft`, `Internal Theft`
`status`	query	string	❌ No	Exact match status (case-sensitive)	Examples: `Open`, `Closed`

Request Body

None

Responses

Status	Content-Type	Description
200	application/json	List of cases (summary view)
400	application/json	Invalid input
401	application/json	Invalid/missing authentication
429	application/json	Rate limit exceeded
500	application/json	Unexpected server error

Response Schema (200 OK)

Array of objects with the following structure:

[
  {
    "id": "a0lAw000004PBXSIA4",
    "incident_type": "Theft",
    "investigation_type": "External Theft",
    "incident_number": "C-20",
    "location_number": "LOC-1001",
    "location_id": "001Aw00000iaXKJIA2",
    "narrative": "Multiple suspects involved in organized retail theft",
    "status": "New",
    "total_estimated_value": 509.97,
    "incident_local_date": "2024-10-06",
    "incident_local_time": "14:30:00.000Z",
    "report_local_date": "2024-10-06",
    "report_local_time": "15:00:00.000Z",
    "police_department": null,
    "police_report_number": null,
    "police_officer_name": null,
    "concealment_method": null,
    "concealment_location": null,
    "uuid": "10eb033f-3ff9-4cc6-b151-ece9cd417314",
    "last_modified_date": "2025-11-04T16:45:34.000Z"
  }
]

Examples

Success Response (200):

[
  {
    "last_modified_date": "2025-11-04T16:45:34.000Z",
    "concealment_location": null,
    "concealment_method": null,
    "uuid": "10eb033f-3ff9-4cc6-b151-ece9cd417314",
    "police_officer_name": null,
    "police_report_number": null,
    "police_department": null,
    "report_local_time": "15:00:00.000Z",
    "report_local_date": "2024-10-06",
    "incident_local_time": "14:30:00.000Z",
    "incident_local_date": "2024-10-06",
    "total_estimated_value": 0.00,
    "status": "New",
    "narrative": "Multiple suspects involved in organized retail theft",
    "location_id": null,
    "location_number": null,
    "incident_number": "C-20",
    "investigation_type": "External Theft",
    "incident_type": "Theft",
    "id": "a0lAw000004PBXSIA4"
  },
  {
    "last_modified_date": "2025-11-04T16:44:15.000Z",
    "concealment_location": null,
    "concealment_method": null,
    "uuid": "712ffe7c-927e-46b4-b8a7-9baef219986d",
    "police_officer_name": null,
    "police_report_number": null,
    "police_department": null,
    "report_local_time": null,
    "report_local_date": null,
    "incident_local_time": "09:15:00.000Z",
    "incident_local_date": "2025-11-01",
    "total_estimated_value": 4520.00,
    "status": "In Progress",
    "narrative": null,
    "location_id": "001Aw00000iaXKJIA2",
    "location_number": "LOC-1001",
    "incident_number": "C-0",
    "investigation_type": "External",
    "incident_type": "Burglary",
    "id": "a0lAw000004PFb3IAG"
  }
]

Error Response (400 - Invalid Date):

{
  "error": "Invalid date format: invalid-date-format",
  "message": "Invalid input data.",
  "success": false
}

Error Response (401 - Session Expired):

[
  {
    "message": "Session expired or invalid",
    "errorCode": "INVALID_SESSION_ID"
  }
]

Notes

Filters use AND logic (all provided filters must match)
Date filters support open-ended ranges (only from or only to)
Text filters are case-sensitive exact matches
Returns summary view (excludes nested persons/vehicles/items)

Cases — Create Case

Method/Path: POST /incidents
Summary: Create Case
Operation ID: createIncident
Auth: bearerAuth (OAuth 2.0)

Parameters

Name	In	Type	Required	Description	Notes
`API-Version`	header	string	✅ Yes	API version	Default: `1.0`
`Source`	header	string	❌ No	Data source for special processing	Enum: `FlockSafety`

Request Body

Content-Type: application/json Required: ✅ Yes

Field Categories:

Read-Only Fields (Ignored if Sent):

incident_number - AutoNumber field (format: C-{number})
total_estimated_value - Roll-up from Case Items
total_recovered_value - Roll-up from recovered Case Items
Audit fields: created_date, last_modified_date, etc.

Date/Time Handling:

Preferred: incident_local_date + incident_local_time (separate fields)
Alternative: incident_date_time (ISO 8601 combined)
Default: If only date provided, time = midnight

Location Fields (Lookup Precedence):

location_number - External identifier (for lookup)
location_id - Direct Salesforce ID
Rule: If both provided, location_id takes precedence

Value Fields:

initial_case_value - Writable estimate at creation
Total case value auto-calculated from Case Items (read-only)

Key Fields:

Field	Type	Required	Description	Max Length	Notes
`incident_type`	string	❌ No	Incident type	-	Example: `Organized Retail Crime`
`investigation_type`	string	❌ No	Investigation type	-	Example: `External Theft`
`narrative`	string	❌ No	Case narrative	32000	-
`status`	string	❌ No	Case status	-	Example: `New`
`location_id`	string	❌ No	Location Salesforce ID	-	Pattern: `^[a-zA-Z0-9]{15,18}$`
`incident_local_date`	string (date)	❌ No	Incident date (YYYY-MM-DD)	-	Example: `2024-10-06`
`incident_local_time`	string	❌ No	Incident time (local)	-	Pattern: `HH:mm:ss.SSSZ`, Example: `14:30:00.000Z`
`stage`	string	❌ No	Case stage (writeOnly)	-	Accepted in POST/PATCH, never returned in GET
`source`	string	❌ No	Case source (writeOnly)	-	Accepted in POST/PATCH, never returned in GET
`involved_persons`	array	❌ No	Nested persons	-	Array of `CreatePerson` objects
`vehicles`	array	❌ No	Nested vehicles	-	Array of `CreateVehicle` objects
`stolen_items`	array	❌ No	Nested items	-	Array of `CreateItem` objects

Example (Minimal):

{
  "incident_type": "Organized Retail Crime",
  "incident_local_date": "2024-11-09",
  "narrative": "Minimal case creation",
  "status": "New"
}

Example (Complex with Nested Entities):

{
  "incident_type": "Organized Retail Crime",
  "investigation_type": "External Theft",
  "incident_local_date": "2024-11-09",
  "incident_local_time": "14:30:00.000Z",
  "narrative": "Multiple suspects involved",
  "status": "New",
  "stage": "Investigation",
  "priority": "High",
  "case_owner": "John Smith",
  "investigator": "Jane Doe",
  "involved_persons": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "person_type": "Suspect",
      "date_of_birth": "1985-05-15",
      "address": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "postal_code": "78701"
    }
  ],
  "vehicles": [
    {
      "make": "TOYOTA",
      "model": "CAMRY",
      "year": "2020",
      "license_plate": "ABC123",
      "license_state": "CA"
    }
  ],
  "stolen_items": [
    {
      "description": "Nike Air Max Shoes",
      "quantity": 2,
      "retail_price": 129.99,
      "upc": "123456789012"
    }
  ]
}

Responses

Status	Content-Type	Description
201	application/json	Resource created successfully
400	application/json	Invalid input
401	application/json	Invalid/missing authentication
429	application/json	Rate limit exceeded
500	application/json	Unexpected server error

Response Schema (201 Created)

{
  "id": "a0lAw000003eO6lIAE",
  "success": true,
  "message": "Incident created successfully",
  "attributes": {
    "type": "ThinkLP__Investigation__c",
    "url": "/services/apexrest/ThinkLP/incidents/a0lAw000003eO6lIAE"
  },
  "created_entity_ids": {
    "involved_persons": ["a0mAw000001XyZ1IAK"],
    "vehicles": ["a0nAw000002AbC3IAK"],
    "stolen_items": ["a0oAw000003DeF5IAK"]
  }
}

Examples

Success Response (201 - Simple):

{
  "id": "a0lAw000003eO6lIAE",
  "success": true,
  "message": "Incident created successfully",
  "attributes": {
    "type": "ThinkLP__Investigation__c",
    "url": "/services/apexrest/ThinkLP/incidents/a0lAw000003eO6lIAE"
  }
}

Success Response (201 - Complex with Nested Entities):

{
  "id": "a0lAw000003eO6lIAE",
  "success": true,
  "message": "Incident created successfully",
  "attributes": {
    "type": "ThinkLP__Investigation__c",
    "url": "/services/apexrest/ThinkLP/incidents/a0lAw000003eO6lIAE"
  },
  "created_entity_ids": {
    "involved_persons": ["a0mAw000001XyZ1IAK"],
    "vehicles": ["a0nAw000002AbC3IAK"],
    "stolen_items": ["a0oAw000003DeF5IAK"]
  }
}

Notes

Supports atomic creation of case with nested entities in single request
Source header triggers special processing (e.g., FlockSafety for ALPR data)
WriteOnly fields (stage, source, outcome, etc.) accepted in POST but never returned in GET
Returns Location header with created resource URL

Cases — Get Case

Method/Path: GET /incidents/{incidentId}
Summary: Get Case
Operation ID: getIncidentById
Auth: bearerAuth (OAuth 2.0)

Description:

Retrieve case with all nested entities (persons, vehicles, items).

Parameters

Name	In	Type	Required	Description	Notes
`incidentId`	path	string	✅ Yes	Salesforce case ID	Pattern: `^[a-zA-Z0-9]{15,18}$`, Example: `a0lAw000003eO6lIAE`
`API-Version`	header	string	✅ Yes	API version	Default: `1.0`

Request Body

None

Responses

Status	Content-Type	Description
200	application/json	Case with nested entities (detail view)
401	application/json	Invalid/missing authentication
404	application/json	Resource not found
429	application/json	Rate limit exceeded
500	application/json	Unexpected server error

Response Schema (200 OK)

Extends CaseSummary with nested entities:

{
  "id": "a0lAw000004UCO3IAO",
  "incident_type": "Organized Retail Crime",
  "investigation_type": "External Theft",
  "incident_number": "C-74",
  "narrative": "Updated narrative with additional evidence...",
  "status": "Closed",
  "total_estimated_value": 509.97,
  "incident_local_date": "2024-11-09",
  "incident_local_time": "14:30:00.000Z",
  "uuid": "62203c91-2e4c-440f-8508-30b0c7c21144",
  "last_modified_date": "2025-11-11T19:06:39.000Z",
  "involved_persons": [
    {
      "id": "a0kAw0000042FQUIA2",
      "name": "IC-110",
      "incident_id": "a0lAw000004UCO3IAO",
      "first_name": "Michael",
      "last_name": "Johnson",
      "person_type": "Suspect",
      "date_of_birth": "1990-03-20",
      "email": "michael.johnson@test.com",
      "phone_number": "555-987-6543",
      "address": {
        "addressLine1": null,
        "addressLine2": null,
        "city": null,
        "state": null,
        "zipCode": null,
        "country": null
      }
    }
  ],
  "vehicles": [
    {
      "id": "a0kAw0000042H2VIAU",
      "name": "IC-109",
      "incident_id": "a0lAw000004UCO3IAO",
      "make": "TOYOTA",
      "model": "CAMRY",
      "year": "2020",
      "color": "Blue",
      "license_plate": "ABC123",
      "license_state": "CA"
    }
  ],
  "stolen_items": [
    {
      "id": "a09Aw00000FQYrpIAH",
      "name": "CI-41",
      "incident_id": "a0lAw000004UCO3IAO",
      "category": "Clothing",
      "description": "Nike Air Max Shoes",
      "quantity": 2,
      "retail_price": 129.99,
      "upc": "123456789012"
    }
  ]
}

Examples

Success Response (200):

See #/components/examples/ActualCaseDetail for full example (lines 1808-1931 of spec).

Error Response (404 - Not Found):

{
  "error": "Incident not found: 000000000000000AAA",
  "message": "Resource not found.",
  "success": false
}

Notes

Returns full case detail including all nested persons, vehicles, and items
Address fields returned as nested object with camelCase keys (addressLine1, zipCode, etc.)

Cases — Update Case

Method/Path: PATCH /incidents/{incidentId}
Summary: Update Case
Operation ID: updateIncident
Auth: bearerAuth (OAuth 2.0)

Description:

Partial update - only send fields to change. Omitted fields remain unchanged.

Null Handling: Send null to explicitly clear a field value. Nested Entities: To update persons/vehicles/items, use dedicated child endpoints.

Parameters

Name	In	Type	Required	Description	Notes
`incidentId`	path	string	✅ Yes	Salesforce case ID	Pattern: `^[a-zA-Z0-9]{15,18}$`
`API-Version`	header	string	✅ Yes	API version	Default: `1.0`

Request Body

Content-Type: application/json Required: ✅ Yes

PATCH Semantics:

Omitted fields: Preserved (not modified)
Null values: Clear the field (set to null in database)
Provided values: Update the field
ReadOnly fields: Ignored if sent (incident_number, total_estimated_value, audit fields)

Key Fields (all optional):

Field	Type	Description	Max Length
`incident_type`	string	Incident type	-
`investigation_type`	string	Investigation type	-
`narrative`	string	Case narrative	32000
`status`	string	Case status	-
`location_id`	string	Location Salesforce ID	-
`incident_local_date`	string (date)	Incident date	-
`incident_local_time`	string	Incident time	-
`stage`	string	Case stage (writeOnly)	-
`source`	string	Case source (writeOnly)	-

Example:

{
  "status": "In Progress",
  "narrative": "Updated narrative with new evidence",
  "priority": "High"
}

Responses

Status	Content-Type	Description
200	application/json	Resource updated successfully
400	application/json	Invalid input
401	application/json	Invalid/missing authentication
404	application/json	Resource not found
429	application/json	Rate limit exceeded
500	application/json	Unexpected server error

Response Schema (200 OK)

{
  "id": "a0lAw000003eO6lIAE",
  "success": true,
  "message": "Incident updated successfully",
  "attributes": {
    "type": "ThinkLP__Investigation__c",
    "url": "/services/apexrest/ThinkLP/incidents/a0lAw000003eO6lIAE"
  }
}

Examples

Success Response (200):

{
  "id": "a0lAw000003eO6lIAE",
  "success": true,
  "message": "Incident updated successfully",
  "attributes": {
    "type": "ThinkLP__Investigation__c",
    "url": "/services/apexrest/ThinkLP/incidents/a0lAw000003eO6lIAE"
  }
}

Notes

True PATCH semantics: only send fields to update
Send null to explicitly clear a field
Cannot update nested entities (use child endpoints)
ReadOnly fields ignored if sent