The organisation

Everything in Zentiq belongs to an organisation (org_…): its avatars and knowledge, its portals, its people and their results, its website visitors' requests, its minutes. An API key belongs to one organisation and reaches nothing else: an id from another organisation is 404 not_found, exactly like an id that doesn't exist.

Organisation (org_)
├─ API keys (key_) · webhooks (wh_) and their deliveries (whd_) · events (evt_)
├─ Faces (av_) · voices (vo_) · knowledge packs (kb_) and their documents (doc_)
├─ Personas (pa_): the avatars people talk to · a persona's website widget · duos (duo_)
├─ Portals (portal_) ─ subjects (sub_) ─ sessions (sess_) and results (res_)
│                                      ─ roles: invites (inv_) and candidates (cand_)
│                                      ─ inbox items: leads, bookings, hand-offs (inb_)
└─ Units (unit_): teams and classes ─ memberships (mbr_) ─ people (usr_)

A key acts as an admin#

A key works as an admin of its organisation, limited by its scopes. It passes the same checks a person in the console does (the plan, the go-live check, consent, the rules for young learners and for hiring), and every change it makes is recorded as made by that key.

A key is never an owner: it can't change the plan or billing, delete the organisation, or give or take an owner's place. Some records only an owner may see (face and voice consent records) reach a key only when an owner gives it that scope.

A person decides#

Some decisions are a person's, never a system's: a hiring decision on a candidate, for one. The API takes them, but only with the named member who made them (decidedBy: "usr_…"), and applies the console's rules for that person: they must have opened the candidate's interview (or reviewed it) before declining, and a decline is made one candidate at a time. The key carries the decision; it never counts as the person who made it.

Plans#

GET /v1/me shows the organisation's plan and the features it includes (plan.features). Anything a plan doesn't include, or a limit it sets (how many personas, portals or custom faces), is refused with 403 upgrade_required, naming the feature and the cheapest plan that includes it. Show that to whoever runs the account: only an owner can change the plan, in the console.

Minutes#

Live conversations use prepaid minutes, the same ones the console uses. GET /v1/usage shows the period's use and the minutes left; the usage.threshold webhook warns you before they run out. Typed conversations with website visitors don't use minutes.