ThinkLP
TheftCase API

Involved Persons

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

Attach, update, and detach the people involved in a case.


Attach a person to a Theft Case

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

Supply identity in any of these ways:

  • personId — links an existing canonical Person.
  • inline attributes — firstName, lastName, dateOfBirth and physicalDescription are stored on the involvement itself, with no Person created.
  • employeeId — finds the Person attached to that employee, or creates one, and links it. The employee is a unique identifier, so a Person can be created for it.
  • employeeNumber — the Employee Number of the employee, handled exactly as if the employee's employeeId had been sent.

A person with no personId, employeeId or employeeNumber has no unique identifier, so no Person is created for it.

personId or employeeId may be combined with inline attributes: the Person link and the description are both stored on the involvement (hybrid storage). personId and employeeId may be sent together only when they name the same Person, as when a read body is sent back as a write; if the employee resolves to a different Person the request is rejected with 400 INVARIANT_VIOLATION. A request that supplies none of the identity forms and no inline attribute returns 400 INVARIANT_VIOLATION.

An inline attribute with no column on the involvement (for example height or hairColor) is rejected with 400 INVARIANT_VIOLATION naming the property. An employeeNumber that matches no employee or several, and an employeeId or personId that names no record, return 422 NATURAL_KEY_NOT_FOUND with the field and value that failed. An employeeNumber and an employeeId sent together must name the same employee, or the request returns 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, so no Person is created for it. 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 new junction carries the case-side fields: personRole, chargesFiled, actionTaken, isIdentityConfirmed, apprehensionDateTime, notes, and the civil-recovery flags.

The attach is written all or nothing; if any write fails, every row written so far, including a Person created for the employee, 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 a person 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 a person to a Theft Case › Request Body

Duplicates the attribute set of the `InvolvedPersonDto` schema as a separate inline definition rather than a shared `$ref`; update both when adding or changing a person attribute.
personId
​string | null · salesforce-id

Salesforce Id of the linked Person record. Optional: an involvement may be described only by inline attributes. When supplied, the lookup is stored and any inline description sent on the same request is stored on the involvement too (hybrid storage); the description is never copied onto the Person. On a case POST or PUT, an id that names no Person returns 422 NATURAL_KEY_NOT_FOUND with field personId. Immutable after create.

employeeId
​string | null · salesforce-id · writeOnly

The Salesforce Contact Id of an employee. On a canonical org, the API finds the Person attached to that employee, or creates one, and writes it as personId. Naming the same employee again reuses that Person. Inline description fields sent with employeeId are stored on the same involvement. The submitted employeeId is not stored on the involvement itself; reads return the Person's employee link as personPreview.employeeId. An unknown Contact id returns 422 NATURAL_KEY_NOT_FOUND with field employeeId and writes nothing. When personId is also supplied, both must name the same Person; otherwise the request is rejected with 400 INVARIANT_VIOLATION. On an org configured for inline person data, no Person is created: employeeId is written to the junction's own employee link as an ordinary inline attribute.

employeeNumber
​string | null · writeOnly

Employee Number of the employee, as an alternative to employeeId (write-only; never returned). The employee is then handled exactly as if employeeId had been sent. A number that matches no employee, or several, returns 422 NATURAL_KEY_NOT_FOUND with field employeeNumber and the value sent. If employeeId is also sent it must name the same employee, or the API returns 400 INVARIANT_VIOLATION.

displayName
​string | null

Inline person display name. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

personType
​string | null

Inline person type. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

firstName
​string | null

Person's first name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

middleName
​string | null

Person's middle name. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

lastName
​string | null

Person's last name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

alias
​string | null

Person's alias or nickname. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

dateOfBirth
​string | null · date

Person's date of birth. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

sex
​string | null

Person's sex. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

ethnicity
​string | null

Person's ethnicity. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

email
​string | null

Person's email address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

phone
​string | null

Person's phone number. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

street
​string | null

Street address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

city
​string | null

City. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

state
​string | null

State or province. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

postalCode
​string | null

Postal code. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

country
​string | null

Country. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

height
​string | null

Person's height, as free text. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

weight
​number | null

Person's weight. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

eyeColor
​string | null

Person's eye color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

hairColor
​string | null

Person's hair color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

clothing
​string | null

Free-text description of clothing worn. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

identifyingFeatures
​string | null

Free-text description of identifying features such as scars or tattoos. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

externalId
​string | null

External system identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

thinkLPId
​string | null

ThinkLP-assigned identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

identificationNumber
​string | null

Identification number as the person reported it. Stored on the involvement itself with identificationType: set on create, returned on read.

identificationType
​string | null

Kind of identification identificationNumber holds, for example Driver's License, stored as reported. It is left blank when a number is sent without a type. Stored on the involvement itself: set on create, returned on read.

physicalDescription
​string | null · maxLength: 32768

Free-text physical description of the person, for an Incident that cannot name them. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set. Maximum 32768 characters. Never copied onto a Person.

involvementId
​string | null · maxLength: 36

Caller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. Stored on the junction's unique ThinkLPId column, which holds at most 36 characters, 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. Differs from id, the Salesforce record id that Salesforce assigns when the involvement is inserted: the caller mints involvementId before the record exists and resends it on retry, so a retried request is recognised and an update can find the stored involvement without the Salesforce id. Distinct from thinkLPId, which is an attribute of the Person.

personRole
​string | null

Case-side role of this person. Required on write.

chargesFiled
​string | null
actionTaken
​string | null
isIdentityConfirmed
​boolean | null
apprehensionDateTime
​string | null · date-time
notes
​string | null

Case-side context notes for the new junction.

readyForCivilRecovery
​boolean | null
civilRecoveryCreated
​boolean | null · readOnly

Attach a person 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.

A person associated with a theft case. The link belongs to the case and is identified by `id`. An involvement describes its person in one or both of two ways: a canonical Person record through `personId`, and inline attributes stored on the involvement itself. At least one of `personId`, `employeeId`, `employeeNumber` or an inline attribute must be supplied. Naming an employee with `employeeId` finds or creates that employee's Person and links it; a person with no `personId` or `employeeId` has no unique identifier, so no Person is created and the involvement stays description-only. On a default org the involvement stores `firstName`, `lastName`, `dateOfBirth`, `physicalDescription` and `involvementId` on its own columns. Any other inline person attribute (for example `height` or `hairColor`) has no column and is rejected with `400 INVARIANT_VIOLATION` naming the property, never silently dropped; the referenced Person's own attributes read back only under `personPreview`. personRole is required in every case. The top-level name, date of birth and other description fields report only what the involvement itself stores, so a body read from the API and sent back unchanged writes nothing derived from the Person onto the involvement. Read paths populate `personPreview` with the Person's display name, type and attributes.
personRole
​string · enum · required

Role of the person in this case.

Enum values:
Suspect
Primary Suspect
Witness
Reporter
Current Employee
Former Employee
Customer
Law Enforcement
replayed
​boolean · enum · required

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

Enum values:
id
​string | null

Salesforce Id of the underlying junction record, assigned by Salesforce on insert. Omit on POST to create a new junction. Not the caller identifier of the involvement, which is involvementId.

personId
​string | null

Salesforce Id of the linked Person record. Optional: an involvement may be described only by inline attributes. When supplied, the lookup is stored and any inline description sent on the same request is stored on the involvement too (hybrid storage); the description is never copied onto the Person. On a case POST or PUT, an id that names no Person returns 422 NATURAL_KEY_NOT_FOUND with field personId. Immutable after create.

employeeId
​string | null · salesforce-id

The Salesforce Contact Id of an employee. On a canonical org, the API finds the Person attached to that employee, or creates one, and writes it as personId. Naming the same employee again reuses that Person. Inline description fields sent with employeeId are stored on the same involvement. The submitted employeeId is not stored on the involvement itself; reads return the Person's employee link as personPreview.employeeId. An unknown Contact id returns 422 NATURAL_KEY_NOT_FOUND with field employeeId and writes nothing. When personId is also supplied, both must name the same Person; otherwise the request is rejected with 400 INVARIANT_VIOLATION. On an org configured for inline person data, no Person is created: employeeId is written to the junction's own employee link as an ordinary inline attribute.

employeeNumber
​string | null

Employee Number of the employee, as an alternative to employeeId (write-only; never returned). Every number in the request resolves in one call; the employee is then handled exactly as if employeeId had been sent. A number that matches no employee, or several, returns 422 NATURAL_KEY_NOT_FOUND with field employeeNumber and the value sent. If employeeId is also sent it must name the same employee, or the API returns 400 INVARIANT_VIOLATION.

displayName
​string | null

Person display name. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

personType
​string | null · enum

Person type (EMPLOYEE or EXTERNAL). Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

Enum values:
EMPLOYEE
EXTERNAL
firstName
​string | null

Person's first name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

middleName
​string | null

Person's middle name. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

lastName
​string | null

Person's last name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

alias
​string | null

Person's alias or nickname. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

dateOfBirth
​string | null · date

Person's date of birth. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

sex
​string | null

Person's sex. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

ethnicity
​string | null

Person's ethnicity. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

email
​string | null

Person's email address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

phone
​string | null

Person's phone number. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

street
​string | null

Street address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

city
​string | null

City. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

state
​string | null

State or province. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

postalCode
​string | null

Postal code. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

country
​string | null

Country. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

height
​string | null

Person's height, as free text. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

weight
​number | null

Person's weight. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

eyeColor
​string | null

Person's eye color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

hairColor
​string | null

Person's hair color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

clothing
​string | null

Free-text description of clothing worn. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

identifyingFeatures
​string | null

Free-text description of identifying features such as scars or tattoos. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

externalId
​string | null

External system identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

thinkLPId
​string | null

ThinkLP-assigned identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

identificationNumber
​string | null

Identification number as the person reported it. Stored on the involvement itself with identificationType: set on create, returned on read.

identificationType
​string | null

Kind of identification identificationNumber holds, for example Driver's License, stored as reported. It is left blank when a number is sent without a type. Stored on the involvement itself: set on create, returned on read.

physicalDescription
​string | null · maxLength: 32768

Free-text physical description of the person, for an Incident that cannot name them. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set. Maximum 32768 characters. Never copied onto a Person.

involvementId
​string | null · maxLength: 36

Caller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. Stored on the junction's unique ThinkLPId column, which holds at most 36 characters, 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. Differs from id, the Salesforce record id that Salesforce assigns when the involvement is inserted: the caller mints involvementId before the record exists and resends it on retry, so a retried request is recognised and an update can find the stored involvement without the Salesforce id. Distinct from thinkLPId, which is an attribute of the Person.

​PersonPreviewDto | null · readOnly

Read-only preview of the referenced Person. Returned as null when the underlying Person is deleted, archived, or FLS-stripped for the running user (graceful degradation). The InvolvedPerson record itself is still valid case data.

isIdentityConfirmed
​boolean | null

Investigator-confirmed identity flag.

actionTaken
​string | null

Free-text description of action taken with this person.

chargesFiled
​string | null · enum

Tri-state charges-filed status (Yes / No / Pending). Backed by the ThinkLP__ChargesFiled__c picklist. Independent of apprehensionDateTime.

Enum values:
Yes
No
Pending
apprehensionDateTime
​string | null · date-time

When the person was apprehended.

notes
​string | null

Free-text investigator notes about this person.

readyForCivilRecovery
​boolean | null

Trigger flag set by investigator to request civil-recovery workflow.

civilRecoveryCreated
​boolean | null · readOnly

Stamped by downstream workflow when the civil-recovery record is created. Read-only on write. The API ignores any value you send.


Detach involved persons from a Theft Case

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

Detaches the involved persons named by involvementIds, the caller-minted ids, or by ids, the involvement row ids. The canonical Person records are not deleted. Sending both, or neither, returns 400 BAD_REQUEST. An id that does not belong to the case returns 404 NOT_FOUND, so a caller cannot reach another case's rows. 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 involved persons 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 involved persons 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 InvolvedPersonId values. Send either ids or involvementIds, not both.

Detach involved persons 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}/involved-persons/link

Links a stored involved person to a canonical Person, named by personId, employeeId or externalId, and returns the updated involved person. caseId in the path is a Salesforce id or an Incident uuid, resolved the same way as on the other involvement routes. The link sets isIdentityConfirmed to false, because a link is a claim an investigator has yet to confirm. Only this route changes the personId of a stored involved person: a PUT of the case that sends a different personId for a stored involved person returns 400 IMMUTABLE_FIELD. An employeeId resolves as it does when a case is taken in: the employee's Person is linked, or created first when the employee has none, and an employeeId that names no employee returns 422 NATURAL_KEY_NOT_FOUND naming employeeId. An org that stores involved persons inline has no Person to link, so the route refuses every key, personId, employeeId and externalId, with 400 INVARIANT_VIOLATION naming inline storage, before any key is looked up and before any Person is created. Apart from that employee Person, linking never creates a canonical record and never changes one, and the reported details on the involved person are kept as they are. Linking an involved person 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 natural key that names several returns 422 NATURAL_KEY_AMBIGUOUS with the matching ids. Send no key, or more than one of personId, employeeId and externalId, 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. The ids in an ambiguous answer are for Salesforce-side callers; a caller outside Salesforce settles the ambiguity with a more specific natural key.

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 involved person on this case, compared without regard to case. It names the involved person to link; a value the case does not hold returns 404 NOT_FOUND.

personId
​string · salesforce-id

Salesforce id of the canonical Person to link.

employeeId
​string · salesforce-id

Salesforce Contact Id of an employee whose Person to link. The employee's Person is linked, or created first when the employee has none. An id that names no employee returns 422 NATURAL_KEY_NOT_FOUND naming employeeId.

externalId
​string

External id of the canonical Person to link. It names an employment, so one that matches several Persons returns 422 NATURAL_KEY_AMBIGUOUS.

replace
​boolean

Set true to replace a different record the involved person already names. Without it, an involved person 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: personId
type = object · requires: employeeId
type = object · requires: externalId
Properties for Variant 1:
personId
​string · salesforce-id · required

Salesforce id of the canonical Person to link.

involvementId
​string

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

employeeId
​string · salesforce-id

Salesforce Contact Id of an employee whose Person to link. The employee's Person is linked, or created first when the employee has none. An id that names no employee returns 422 NATURAL_KEY_NOT_FOUND naming employeeId.

externalId
​string

External id of the canonical Person to link. It names an employment, so one that matches several Persons returns 422 NATURAL_KEY_AMBIGUOUS.

replace
​boolean

Set true to replace a different record the involved person already names. Without it, an involved person already linked to a different record returns 409 ALREADY_LINKED.

Default: false

OK — the updated involved person. Linking to the record the involved person already names returns 200 and changes nothing.

A person associated with a theft case. The link belongs to the case and is identified by `id`. An involvement describes its person in one or both of two ways: a canonical Person record through `personId`, and inline attributes stored on the involvement itself. At least one of `personId`, `employeeId`, `employeeNumber` or an inline attribute must be supplied. Naming an employee with `employeeId` finds or creates that employee's Person and links it; a person with no `personId` or `employeeId` has no unique identifier, so no Person is created and the involvement stays description-only. On a default org the involvement stores `firstName`, `lastName`, `dateOfBirth`, `physicalDescription` and `involvementId` on its own columns. Any other inline person attribute (for example `height` or `hairColor`) has no column and is rejected with `400 INVARIANT_VIOLATION` naming the property, never silently dropped; the referenced Person's own attributes read back only under `personPreview`. personRole is required in every case. The top-level name, date of birth and other description fields report only what the involvement itself stores, so a body read from the API and sent back unchanged writes nothing derived from the Person onto the involvement. Read paths populate `personPreview` with the Person's display name, type and attributes.
personRole
​string · enum · required

Role of the person in this case.

Enum values:
Suspect
Primary Suspect
Witness
Reporter
Current Employee
Former Employee
Customer
Law Enforcement
id
​string | null

Salesforce Id of the underlying junction record, assigned by Salesforce on insert. Omit on POST to create a new junction. Not the caller identifier of the involvement, which is involvementId.

personId
​string | null

Salesforce Id of the linked Person record. Optional: an involvement may be described only by inline attributes. When supplied, the lookup is stored and any inline description sent on the same request is stored on the involvement too (hybrid storage); the description is never copied onto the Person. On a case POST or PUT, an id that names no Person returns 422 NATURAL_KEY_NOT_FOUND with field personId. Immutable after create.

employeeId
​string | null · salesforce-id

The Salesforce Contact Id of an employee. On a canonical org, the API finds the Person attached to that employee, or creates one, and writes it as personId. Naming the same employee again reuses that Person. Inline description fields sent with employeeId are stored on the same involvement. The submitted employeeId is not stored on the involvement itself; reads return the Person's employee link as personPreview.employeeId. An unknown Contact id returns 422 NATURAL_KEY_NOT_FOUND with field employeeId and writes nothing. When personId is also supplied, both must name the same Person; otherwise the request is rejected with 400 INVARIANT_VIOLATION. On an org configured for inline person data, no Person is created: employeeId is written to the junction's own employee link as an ordinary inline attribute.

employeeNumber
​string | null

Employee Number of the employee, as an alternative to employeeId (write-only; never returned). Every number in the request resolves in one call; the employee is then handled exactly as if employeeId had been sent. A number that matches no employee, or several, returns 422 NATURAL_KEY_NOT_FOUND with field employeeNumber and the value sent. If employeeId is also sent it must name the same employee, or the API returns 400 INVARIANT_VIOLATION.

displayName
​string | null

Person display name. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

personType
​string | null · enum

Person type (EMPLOYEE or EXTERNAL). Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

Enum values:
EMPLOYEE
EXTERNAL
firstName
​string | null

Person's first name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

middleName
​string | null

Person's middle name. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

lastName
​string | null

Person's last name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

alias
​string | null

Person's alias or nickname. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

dateOfBirth
​string | null · date

Person's date of birth. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

sex
​string | null

Person's sex. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

ethnicity
​string | null

Person's ethnicity. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

email
​string | null

Person's email address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

phone
​string | null

Person's phone number. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

street
​string | null

Street address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

city
​string | null

City. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

state
​string | null

State or province. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

postalCode
​string | null

Postal code. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

country
​string | null

Country. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

height
​string | null

Person's height, as free text. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

weight
​number | null

Person's weight. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

eyeColor
​string | null

Person's eye color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

hairColor
​string | null

Person's hair color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

clothing
​string | null

Free-text description of clothing worn. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

identifyingFeatures
​string | null

Free-text description of identifying features such as scars or tattoos. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

externalId
​string | null

External system identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

thinkLPId
​string | null

ThinkLP-assigned identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

identificationNumber
​string | null

Identification number as the person reported it. Stored on the involvement itself with identificationType: set on create, returned on read.

identificationType
​string | null

Kind of identification identificationNumber holds, for example Driver's License, stored as reported. It is left blank when a number is sent without a type. Stored on the involvement itself: set on create, returned on read.

physicalDescription
​string | null · maxLength: 32768

Free-text physical description of the person, for an Incident that cannot name them. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set. Maximum 32768 characters. Never copied onto a Person.

involvementId
​string | null · maxLength: 36

Caller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. Stored on the junction's unique ThinkLPId column, which holds at most 36 characters, 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. Differs from id, the Salesforce record id that Salesforce assigns when the involvement is inserted: the caller mints involvementId before the record exists and resends it on retry, so a retried request is recognised and an update can find the stored involvement without the Salesforce id. Distinct from thinkLPId, which is an attribute of the Person.

​PersonPreviewDto | null · readOnly

Read-only preview of the referenced Person. Returned as null when the underlying Person is deleted, archived, or FLS-stripped for the running user (graceful degradation). The InvolvedPerson record itself is still valid case data.

isIdentityConfirmed
​boolean | null

Investigator-confirmed identity flag.

actionTaken
​string | null

Free-text description of action taken with this person.

chargesFiled
​string | null · enum

Tri-state charges-filed status (Yes / No / Pending). Backed by the ThinkLP__ChargesFiled__c picklist. Independent of apprehensionDateTime.

Enum values:
Yes
No
Pending
apprehensionDateTime
​string | null · date-time

When the person was apprehended.

notes
​string | null

Free-text investigator notes about this person.

readyForCivilRecovery
​boolean | null

Trigger flag set by investigator to request civil-recovery workflow.

civilRecoveryCreated
​boolean | null · readOnly

Stamped by downstream workflow when the civil-recovery record is created. Read-only on write. The API ignores any value you send.


Update the case-side fields of one involved-person junction

PUT
https://yourorg.my.salesforce.com/services/apexrest/ThinkSDK/thinklp/api/v1
/theft-cases/{caseId}/involved-persons/{junctionId}

Updates only the supplied case-side fields (personRole, chargesFiled, actionTaken, isIdentityConfirmed, apprehensionDateTime, notes, civil-recovery flags) on one junction. The junction's identity (id, theftCaseId, personId) and canonical link are preserved. personId, employeeId, displayName, personType, and every other inline person attribute are not accepted by this operation; if included in the request body they are silently ignored and the person's existing stored values are left unchanged. A junctionId that does not belong to caseId returns 404 NOT_FOUND, so a caller cannot reach another case's rows. personRole is still required on write. involvementId is immutable: a body that carries a different value for a stored involvement returns 400 IMMUTABLE_FIELD, where a value differing only in case counts as the same value. The change is written all or nothing; if any write fails, every row written so far is rolled back.

Update the case-side fields of one involved-person junction › path Parameters

caseId
​string · salesforce-id · required

Salesforce Investigation record Id of the parent theft case

junctionId
​string · salesforce-id · required

InvolvedPersonId of the junction row to update.

Update the case-side fields of one involved-person junction › Request Body

personRole
​string · required
chargesFiled
​string | null
actionTaken
​string | null
isIdentityConfirmed
​boolean | null
apprehensionDateTime
​string | null · date-time
notes
​string | null
readyForCivilRecovery
​boolean | null
civilRecoveryCreated
​boolean | null

Update the case-side fields of one involved-person junction › Responses

OK — updated junction body returned.

A person associated with a theft case. The link belongs to the case and is identified by `id`. An involvement describes its person in one or both of two ways: a canonical Person record through `personId`, and inline attributes stored on the involvement itself. At least one of `personId`, `employeeId`, `employeeNumber` or an inline attribute must be supplied. Naming an employee with `employeeId` finds or creates that employee's Person and links it; a person with no `personId` or `employeeId` has no unique identifier, so no Person is created and the involvement stays description-only. On a default org the involvement stores `firstName`, `lastName`, `dateOfBirth`, `physicalDescription` and `involvementId` on its own columns. Any other inline person attribute (for example `height` or `hairColor`) has no column and is rejected with `400 INVARIANT_VIOLATION` naming the property, never silently dropped; the referenced Person's own attributes read back only under `personPreview`. personRole is required in every case. The top-level name, date of birth and other description fields report only what the involvement itself stores, so a body read from the API and sent back unchanged writes nothing derived from the Person onto the involvement. Read paths populate `personPreview` with the Person's display name, type and attributes.
personRole
​string · enum · required

Role of the person in this case.

Enum values:
Suspect
Primary Suspect
Witness
Reporter
Current Employee
Former Employee
Customer
Law Enforcement
id
​string | null

Salesforce Id of the underlying junction record, assigned by Salesforce on insert. Omit on POST to create a new junction. Not the caller identifier of the involvement, which is involvementId.

personId
​string | null

Salesforce Id of the linked Person record. Optional: an involvement may be described only by inline attributes. When supplied, the lookup is stored and any inline description sent on the same request is stored on the involvement too (hybrid storage); the description is never copied onto the Person. On a case POST or PUT, an id that names no Person returns 422 NATURAL_KEY_NOT_FOUND with field personId. Immutable after create.

employeeId
​string | null · salesforce-id

The Salesforce Contact Id of an employee. On a canonical org, the API finds the Person attached to that employee, or creates one, and writes it as personId. Naming the same employee again reuses that Person. Inline description fields sent with employeeId are stored on the same involvement. The submitted employeeId is not stored on the involvement itself; reads return the Person's employee link as personPreview.employeeId. An unknown Contact id returns 422 NATURAL_KEY_NOT_FOUND with field employeeId and writes nothing. When personId is also supplied, both must name the same Person; otherwise the request is rejected with 400 INVARIANT_VIOLATION. On an org configured for inline person data, no Person is created: employeeId is written to the junction's own employee link as an ordinary inline attribute.

employeeNumber
​string | null

Employee Number of the employee, as an alternative to employeeId (write-only; never returned). Every number in the request resolves in one call; the employee is then handled exactly as if employeeId had been sent. A number that matches no employee, or several, returns 422 NATURAL_KEY_NOT_FOUND with field employeeNumber and the value sent. If employeeId is also sent it must name the same employee, or the API returns 400 INVARIANT_VIOLATION.

displayName
​string | null

Person display name. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

personType
​string | null · enum

Person type (EMPLOYEE or EXTERNAL). Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

Enum values:
EMPLOYEE
EXTERNAL
firstName
​string | null

Person's first name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

middleName
​string | null

Person's middle name. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

lastName
​string | null

Person's last name. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

alias
​string | null

Person's alias or nickname. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

dateOfBirth
​string | null · date

Person's date of birth. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set.

sex
​string | null

Person's sex. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

ethnicity
​string | null

Person's ethnicity. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

email
​string | null

Person's email address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

phone
​string | null

Person's phone number. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

street
​string | null

Street address. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

city
​string | null

City. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

state
​string | null

State or province. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

postalCode
​string | null

Postal code. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

country
​string | null

Country. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

height
​string | null

Person's height, as free text. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

weight
​number | null

Person's weight. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

eyeColor
​string | null

Person's eye color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

hairColor
​string | null

Person's hair color. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

clothing
​string | null

Free-text description of clothing worn. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

identifyingFeatures
​string | null

Free-text description of identifying features such as scars or tattoos. Stored on the involvement itself, beside the optional Person link, as the person was reported: set on create, returned on read whether or not personId is set. The referenced Person's own value appears only under personPreview.

externalId
​string | null

External system identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

thinkLPId
​string | null

ThinkLP-assigned identifier for the person. Inline-detail attribute — set on create, returned on read. Reports only a value stored on the involvement itself; the referenced Person's own value appears under personPreview. A value the org has no field on the involvement for is rejected with 400 INVARIANT_VIOLATION, with or without a personId or employeeId. Writable only on orgs configured to store person details inline.

identificationNumber
​string | null

Identification number as the person reported it. Stored on the involvement itself with identificationType: set on create, returned on read.

identificationType
​string | null

Kind of identification identificationNumber holds, for example Driver's License, stored as reported. It is left blank when a number is sent without a type. Stored on the involvement itself: set on create, returned on read.

physicalDescription
​string | null · maxLength: 32768

Free-text physical description of the person, for an Incident that cannot name them. Stored on the involvement itself, beside the optional Person link: set on create, returned on read whether or not personId is set. Maximum 32768 characters. Never copied onto a Person.

involvementId
​string | null · maxLength: 36

Caller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. Stored on the junction's unique ThinkLPId column, which holds at most 36 characters, 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. Differs from id, the Salesforce record id that Salesforce assigns when the involvement is inserted: the caller mints involvementId before the record exists and resends it on retry, so a retried request is recognised and an update can find the stored involvement without the Salesforce id. Distinct from thinkLPId, which is an attribute of the Person.

​PersonPreviewDto | null · readOnly

Read-only preview of the referenced Person. Returned as null when the underlying Person is deleted, archived, or FLS-stripped for the running user (graceful degradation). The InvolvedPerson record itself is still valid case data.

isIdentityConfirmed
​boolean | null

Investigator-confirmed identity flag.

actionTaken
​string | null

Free-text description of action taken with this person.

chargesFiled
​string | null · enum

Tri-state charges-filed status (Yes / No / Pending). Backed by the ThinkLP__ChargesFiled__c picklist. Independent of apprehensionDateTime.

Enum values:
Yes
No
Pending
apprehensionDateTime
​string | null · date-time

When the person was apprehended.

notes
​string | null

Free-text investigator notes about this person.

readyForCivilRecovery
​boolean | null

Trigger flag set by investigator to request civil-recovery workflow.

civilRecoveryCreated
​boolean | null · readOnly

Stamped by downstream workflow when the civil-recovery record is created. Read-only on write. The API ignores any value you send.