Partner API

Partner API

Everything your app needs to hold a connection with a Geena user: a “Connect with Geena” popup that logs the user in and captures consent in one screen, then a small REST plane (/partner/v1) for reading, filling, and maintaining the data the user granted you.

The model in six sentences

1. Your organization publishes a manifest in the Geena dashboard — the versioned shape of what you ask for: slots (a passport, a proof-of-address document, supporting files, …), presentation groups, and terms.
2. When a user consents, Geena mints a connection (internally: an accepted request) pinning that manifest version. The connection id — request_id — is the address of everything else in this API.
3. Data rights come from per-slot grants the user controls, never from OAuth scopes: your tokens carry identity only, and every call re-checks the grant behind it.
4. Every act on the plane — reading a value, listing candidates, attaching, creating, writing, deleting — is receipted to the user’s timeline with your app’s client id. Design your integration expecting the user to see it.
5. A manifest can also ask about parties beyond the account holder — subjects: a family member (“each child you cover”) or a company the user represents (“the investing company”). The user answers those in your app from the family member’s vault or the company’s vault, and every such participant is addressed only by a pairwise alias, meaningless to any other organization.
6. What the user did not grant is invisible: an ungranted, foreign, malformed or nonexistent id all answer the same 404 not_found, and a pending slot is indistinguishable from “the user has no such data” (the oracle rule).

Section contents

• Getting started — organization, app registration, manifest authoring and publishing, wiring the ids into your app.
• Connect with Geena — the popup ceremony, PKCE, the code exchange, token lifecycle, and the organization-access sign-in your back office uses.
• Connections & status — discovering your connections and driving your UI from per-slot status and the cast of participants.
• Reading & writing data — serving granted slots record by record, file content, delegated writes and deletes.
• Filling slots in-app — the native picker: candidates, attach, slot-bound create — for the user, or for a participant.
• Subjects: relatives & companies — manifests about other parties: who could answer, adding a family member, founding a company, filling per participant.
• Recipes — copy-paste sequences for the common jobs: fill, update, relatives, companies, files, login, revocation.
• Errors — the error envelope, code table, unavailable records and sealed keys.
• OpenAPI specification — the machine-readable contract for /partner/v1.

Your organization’s own side of a connection — the copies it kept, the files it holds for a request, the update proposals it decides — is the Organization API, reached with the same kind of token once it carries the organization scope.

Base URLs (test environment)

All /partner/v1 calls take Authorization: Bearer <access token>.