Subjects: relatives & companies

Subjects: relatives & companies

A manifest can ask about parties beyond the account holder: each child you cover, your co-driver, the company you invest through. Those asks are subjects — declared once in the manifest, each typed — and every slot that carries a subject id in /status asks about that party rather than about the user.

Two kinds of party exist, and a subject’s type says which lane it is answered from:

• person — a family member. The user answers with one of their family-member vaults: vaults they own and hold data in on a relative’s behalf, declared with a kinship. The subject fixes the relation (child, spouse, partner, parent, sibling, other).
• company — a legal entity the user represents. The user answers with a company vault: a shared legal-entity vault on which they hold a live Manager key right now. Ownership alone is not enough, and an editor may change a company’s data without being able to hand it to a third party.

Whoever answers is a participant, and your app never sees the vault behind one: every participant is addressed by a pairwise alias — stable across your organization’s connections with that party, meaningless to any other organization, never a vault id.

Four rules shape everything on this page:

• Type- and relation-scoped. A child subject can only ever be answered by family members the user holds as children; a company subject only by a company the user manages. The type and the relation come from the manifest, never from your app.
• One participant, one role. Within a connection, a party answering one subject is excluded from answering a different one. A subject with repeat: false asks about exactly one party: binding a second answers 403 participant_ineligible.
• Standing is re-checked every time. Whether the user may still speak for a company is decided on every read and every write, never trusted from grant time: losing the Manager role renders that company’s records unavailable (see Reading & writing data) without touching a grant or a copy your organization kept — and regaining it serves them again with no re-consent.
• Labels are the user’s. A participant’s display name — the child’s name, the company’s name as the user knows it — appears in exactly one response (the subject’s candidates) and is never accepted from or served back to any other partner surface.

Discover the cast

GET /status lists the manifest’s subjects, who currently answers them, and marks their slots:

{
  "subjects": [
    { "id": "child", "type": "person", "relation": "child",
      "label": "Each child you cover", "repeat": true },
    { "id": "investing-company", "type": "company",
      "label": "Investing company", "repeat": false }
  ],
  "participants": [
    { "subjectId": "child", "type": "person", "alias": "c0ffee12-…" }
  ],
  "items": [
    { "slotId": "9e01…", "label": "Child's name", "subject": "child",
      "kind": "schema", "target": "PersonFullName", "verbs": ["fill", "keep"],
      "status": "granted" },
    { "slotId": "3b8f…", "label": "Company details", "subject": "investing-company",
      "kind": "schema", "target": "LegalEntity", "verbs": ["fill", "edit", "keep"],
      "status": "pending" }
  ]
}

repeat: true means 0..N participants — the user chooses how many by binding family members or companies. participants is derived from the grants, never stored, and absent while nobody is bound. Slot status aggregates across the bound parties; drive per-party state from the fill surface below and from the per-record participant on served slots.

List who could answer

GET /partner/v1/requests/{requestId}/subjects/{subjectId}/candidates

The subject half of the fill surface: who the user could put behind this subject, in the lane its type dispatches on — family members whose relation matches, or companies the user manages right now — minus anyone already answering a different subject of this connection. Requires fill on at least one of the subject’s slots; receipted (listed, coalesced) like every enumeration.

{
  "subjectId": "child",
  "type": "person",
  "relation": "child",
  "label": "Each child you cover",
  "repeat": true,
  "participants": [
    { "alias": "c0ffee12-…", "label": "Alma", "bound": true },
    { "alias": "beef4477-…", "label": "Sixten", "bound": false }
  ]
}

{
  "subjectId": "investing-company",
  "type": "company",
  "label": "Investing company",
  "repeat": false,
  "participants": [
    { "alias": "9a7f…", "label": "Acme B.V.", "bound": false,
      "details": { "registrationCountry": "NL", "registrationNumber": "12345678" } }
  ]
}

bound: true marks parties already answering this subject — render them as covered. The label is the user’s own name for the party; treat it as display-only. A company candidate may carry details — the registration country and number read from the company’s own record, so a user with two companies can tell them apart in your picker. It is best-effort: absent when the record does not exist yet or cannot be opened, and never present on a person.

Add a participant

POST /partner/v1/requests/{requestId}/subjects/{subjectId}/participants
Content-Type: application/json

{ "label": "Alma" }

Your app supplies a name and nothing else; what is minted follows the subject’s type:

• person — “add a child”. Mints a family-member vault owned by the user. The relation comes from the subject’s declaration, the label from what the user typed in your UI (ask for it explicitly: “their name — stays in your Geena”). The user’s plan bounds how many family-member vaults they may hold; at the cap the call answers 403 limit_reached.
• company — “found a company”. Mints a legal-entity shared vault founded by the user, exactly as they would found one in Geena: they are its owner with a live Manager key, so the company appears among the subject’s candidates at once and its records may answer the subject’s slots. Registration details are not taken here — they are filled into the subject’s slots like any other record. Adding collaborators, the ownership structure and registry enrichment stay first-party in Geena, and so does joining a company that already exists: the user accepts its manager’s invitation in Geena, and the company then shows up among the candidates.

The response is a participant ready to answer slots:

{ "alias": "c0ffee12-…", "label": "Alma" }

No receipt row is written for the creation itself — the vault is the user’s own state; its later grants are the receipts. The call is not idempotent: disable the button while one is in flight. A deployment without company founding answers 409 subject_kind_unsupported on a company subject.

Fill a subject’s slots

Every fill route takes the participant — as a query parameter or a body field:

GET  …/slots/{slotId}/candidates?participant=c0ffee12-…
POST …/slots/{slotId}/attach          { "resourceId": "…", "participant": "c0ffee12-…" }
POST …/slots/{slotId}                 { "participant": "c0ffee12-…", "name": "…", "data": { … } }
POST …/slots/{slotId}                 multipart: participant=9a7f… label=… file=@extract.pdf

Candidates then list the participant’s vault (their documents, with current data where decryptable), attach grants their existing item, create mints a fresh document or file in their vault and grants it in the same act. On a subject slot the participant is required (422 participant_required); on a recipient slot it is refused (422 participant_not_allowed); an alias naming nobody the user may answer with — or a different party than the resource belongs to — answers 404 participant_unknown.

Served records for subject slots carry the participant back to you — the participant block with the alias — so a slot answered by two children yields two records you can tell apart. See Reading & writing data.