Entities

Entities are the things your events point at: the reader that recorded a badge, the person behind it, the badge itself. You never have to declare them before sending events — declaring them is how you enrich what sinio.ai already knows, not how you unlock ingestion.

Declared and undeclared

An event naming a device sinio.ai has never seen is accepted, and the device is created as undeclared. It works, it accumulates history, and it shows up in the console with a flag asking someone to qualify it.

Upserting that same entity later flips it to declared, keeping every event already attached to it. This is why the order of your integration does not matter: push events on day one, tidy the reference on day three, and nothing is lost or rewritten in between.

An entity belongs to the source whose key declares or sends it. When two of your tools name the same person or the same device — 2 in one, E123 in the other — keep sending each its own; link them once in the console (Settings › Identifiers: attach the pair, or a matching rule when both write the same external_id), and episodes, reports and habits count them as one.

The entity model

Properties

Name
external_id
Type
string
Description
Required. Your identifier. Together with kind, it is the upsert key.
Name
kind
Type
string
Description
Required. One of device, subject, asset, actor, credential.
Name
subkind
Type
string
Description
Optional. Your own finer classification — borne_nfc, forklift, temperature_probe. An unknown value never fails the call: it is created undeclared, for someone to qualify in the console. In each project a subkind carries a profile — the measures its entities are expected to send — and norms can be set on it (Measurements).
Name
label
Type
string
Description
Optional. Human-readable name, shown in the console and in reports.
Name
location
Type
string
Description
Optional. The external_id of the location this entity sits in. It must already exist — unlike subkinds, an unknown location is rejected with unknown_location.
Name
attributes
Type
object
Description
Optional. Free-form metadata: firmware version, model, serial number.

The five kinds

Name
device
Type
kind
Description
Produces or records events: readers, sensors, terminals, gateways.
Name
subject
Type
kind
Description
What events are about: a person, a vehicle, a room, anything that accumulates a history worth reading.
Name
credential
Type
kind
Description
What identifies a subject in the field: a badge, a tag, a card. Bound to a subject over time through assignments.
Name
actor
Type
kind
Description
Who performed the action, when that is not the subject — a technician closing someone else's work order.
Name
asset
Type
kind
Description
Equipment that is acted upon rather than acting: a machine under maintenance, a container being tracked.

POST/v1/entities

Upsert entities

Bulk upsert keyed on (kind, external_id) within the source, up to 500 per call.

Required attributes

Name
entities
Type
array
Description
Up to 500 entities.

Headers

Name
Authorization
Type
string
Description
Bearer <api_key>.

Rejection codes

Name
unknown_location
Type
code
Description
The location does not exist. Declare it first with POST /v1/locations.

Request

POST

/v1/entities

curl https://api.sinio.ai/v1/entities \
  -H "Authorization: Bearer $SINIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": [
      {
        "external_id": "BORNE-A12",
        "kind": "device",
        "subkind": "borne_nfc",
        "label": "Hall reader A12",
        "location": "SITE-A.HALL",
        "attributes": { "firmware": "2.4.1" }
      },
      { "external_id": "P-4582", "kind": "subject", "label": "Marie Lefèvre" },
      { "external_id": "04A2B9C1", "kind": "credential" }
    ]
  }'

Response

{
  "accepted": 3,
  "rejected": 0,
  "rejections": []
}

Bind credentials to subjects