People
A person is someone known to your account — typically a visitor, contractor, or other site guest — identified by personId. People are referenced from check-ins. See IDs and timestamps for the full ID model.
Identity
Section titled “Identity”People are addressed only by personId:
/profiles/people/{personId}personId is an integer returned when the person is created. Use the same value across check-ins and profile calls so the platform can tie them together.
Operations
Section titled “Operations”Every people endpoint lives under People in the API Reference. Open any operation there for request and response schemas, plus Scalar’s Try it panel for cURL and sample code.
Creating and updating
Section titled “Creating and updating”Creates a person and returns PersonResponse with the new personId. Send an Idempotency-Key on create — see Idempotency.
Applies a partial update: only fields you send are changed.
Removes the person and returns 204 No Content.
Reading people
Section titled “Reading people”The cheapest lookup when you have a single personId.
Search or list people — see PersonSearchRequest. Unknown personIds are omitted. Paging fields: PeopleSearchResponse.
POST-with-body is used instead of GET-with-query-string so filters stay type-checked in one place.
Face images
Section titled “Face images”Person responses may include a faces array when face photos exist. Each entry has an imageId (UUID). Use that id to download the image bytes:
Returns the face image as binary data (image/jpeg or similar). Discover ids from faces[].imageId on PersonResponse.
Labels
Section titled “Labels”Person responses include an embedded labels array. Define person labels under Labels at /labels/people; assign or remove them on a person with PUT /profiles/people/{personId}/labels.
Idempotency keys
Section titled “Idempotency keys”| Operation | Idempotency-Key | Why |
|---|---|---|
POST /profiles/people | Recommended | A retried create must not produce two people. |
PUT /profiles/people/{id} | Optional | A partial update is naturally idempotent. |
DELETE /profiles/people/{id} | Optional | Re-delete returns 404. |
GET / POST …/search | N/A | Reads are safe to retry. |
See Idempotency for the full rules.
Related
Section titled “Related”- Check-ins — people are referenced from check-ins; see the Check-ins guide.
- Errors — Errors.