Requests, records & kept copies
Requests, records & kept copies
List your requests
Every request your organization holds — pending invitations it sent and the
connections people accepted — newest first, optionally narrowed to one
recipient email (normalized, exact). Metadata only, all of it your own, so the
call writes no receipt. Requires request_read.
stateis one ofpending,active,rejected_by_sender,rejected_by_recipient,expired,revoked,suspended, evaluated at call time on both clocks — the invitation window while pending, the accepted terms’ retention window once active — so a connection past retention readsexpired.initiatedByisorg(your team sent it from the dashboard) orrecipient(a person opened it from your app’s hosted ceremony;initiatingClientIdnames the app).manifestVersionis pinned at consent; re-publishing never widens a live connection.
One request in full
The request, the manifest version it pinned and — per slot — whether the
person granted it, plus one records entry per standing answer, the copies
your organization kept, and the open update proposals. One call renders the
organization’s view of a connection; the copies’ values are read separately
below. Requires request_read.
statusisgrantedorpending, per slot — any record granted makes the itemgranted, andpendingstays indistinguishable from “the person has no such data” and from “they never will”. A slot every one of whose records is unavailable is stillgranted: the person said yes and has not taken it back.recordsis where a slot answered by several parties becomes legible. Each entry names itsparticipant—nullfor the recipient’s own item, otherwise{ subjectId, type, alias }withtypein the manifest’s own vocabulary (personorlegal_entity; the partner plane sayscompanyfor the same lane). Thealiasis pairwise: stable across every connection your organization has with that party, unrelated to any other organization’s handle, never a vault id — and the same handle the partner plane and the kept copies carry, so the three line up.sourceVersionis where the person’s resource stands right now; compare it with thesourceVersionof the copy you kept to see whether you hold the current one. Absent on anunavailablerecord.status: unavailablecomes with areason:connection_inactive(the connection itself is revoked or past retention — every record of it is unavailable),participant_ineligible(the recipient may no longer answer for that party: left the company, lost the Manager role, membership revoked), orsource_unavailable(the resource no longer resolves). None of them deletes anything — the grant stands, and any copy already kept is untouched; standing regained makes aparticipant_ineligiblerecordavailableagain.adoptionis thekeepslot’s policy:manual— your team keeps copies explicitly (below);auto— Geena keeps the first version and every later one as soon as they exist, whenever your organization’s key is warm, and queues the copy aspendinguntil a member signs in.
Keep a copy
Materializes a copy of the slot’s currently granted resource(s) into your
organization’s vault — the manual “Keep” on a manual slot, or a first copy
after the fact. Requires the slot’s keep verb and request_manage.
Idempotent per (slot, source version): a version already kept is returned,
never copied twice. Files are kept like records — the copy becomes a version of
the one org file this (request, slot, source file) already has.
The keep is per participant. On a slot several parties answered, send
{"participant": "<alias>"} — the alias from the slot’s own records — to
keep just that party’s records; with no body every standing record is kept. A
record the recipient may no longer answer for does not stop the others: it
comes back in skipped with its reason, and the call still answers 200.
Read skipped on every keep — a 200 whose adoptions is shorter than
the slot’s records is not a failure to report, it is this. Only a keep that
took nothing answers a typed refusal (403 participant_ineligible,
403 adoption_refused; an alias naming no granted record of this slot is the
latter). Retrying is safe, and a retry after standing is regained adds only
what was skipped.
A copy taken while your organization’s key was cold is state: "pending"
with no orgVersion yet; retry the request’s pending copies once a member is
in:
Read the copies you kept
Every materialized adoption of the request with its content — your own copy,
opened with your organization’s key. Requires request_manage. Pending
adoptions are listed on the request detail, not here.
Every copy of one person’s record under one request and slot is a version of one org document, interleaved with your own corrections. Read it as two layers:
datais the copy as kept — the version this adoption pinned (orgVersion,origin: copy).currentDatais the head of that chain — what your organization uses today: the same values unless a newer copy was kept or a member corrected it (currentOrgVersion,currentOrigin: copy | correction).
A consumer that wants what the organization uses today reads currentData of
the newest adoption per slot — and, on a slot the manifest asks about a
subject, per participant within it: two children answering one slot are
two parties, two source records and two chains, and collapsing them by slot
alone would show one child’s data under the other’s question. participant is
snapshotted at keep time, so a copy of a child’s passport keeps saying “this
child” after the grant is superseded or the connection revoked.
A kept file chains the same way — one org file per (request, slot, source
file), one version per keep — but has no values: data is that version’s
metadata (label, fileName, mimeType, fileSize), currentData is
absent, and the bytes of each version come through that adoption’s own
downloadUrl:
Streams the version this adoption kept (not the head) as an attachment,
decrypted with your organization’s key. A document adoption answers
400 unsupported_item; a copy still pending answers 403 adoption_refused.
To read a request’s files as files — kept copies beside your own
attachments, head first — use Request files.
Correct a kept copy
Your organization’s own revision of a copy it keeps — an address in the
format you want, a name cased your way — appended as the next version of the
copy’s chain, tagged correction, held beside what the person gave. It
never changes the person’s data and never reaches them: data you believe
wrong rather than badly shaped is the person’s to fix, through the partner
plane’s edit verb or in Geena.
- It corrects a copy that already exists; it never keeps. Keep first —
correcting a record with no materialized copy answers
403 adoption_refused. Structured records only: a kept file is refused the same way. Requires the slot’skeepverb andrequest_manage. - Pinned to what the member saw. Take the three addressing fields from
the newest materialized keep of the record on
/copies(the one with the highestadoption.sourceVersion):sourceResourceIdandexpectedSourceVersionfrom itsadoption— the person’s record, never the org copy’s ownresourceId— andexpectedOrgVersionfrom itscurrentOrgVersion, the head the correction appends to. A newer source version published since, or another member’s keep or correction, answers409 version_conflictwith nothing written: re-read/copiesand re-apply the edit over what comes back.sourceResourceIdmay be omitted only when the slot holds exactly one granted record. datais the complete corrected document, never a patch, validated against the copy’s own schema — a correction changes the values, never what the record is.
The adoption block is the record’s newest keep, unchanged — a correction
creates no adoption, writes no receipt and changes no consent. orgVersion is
the version the correction became: the new head /copies will report as
currentOrgVersion with currentOrigin: correction, and the value to send as
the next expectedOrgVersion to correct again without a re-read.
Recipe: keep your system in sync
Poll the request detail rather than the partner plane: it is your own material, unreceipted, and it tells you whose record moved.