Connections & status

List your connections

GET /partner/v1/requests
Authorization: Bearer <access token>

Returns every active connection your organization holds with the token’s user — the recovery path when you did not store request_id at connect time. Pending invitations are never listed: before consent there is no connection.

{
  "requests": [
    {
      "requestId": "6f9b2c9e-6a4e-4a44-9d5e-2f0f6f2a9b11",
      "manifestId": "b1af2d3c-9c1f-4f6e-8f2a-77aa01c2d9f0",
      "manifestName": "Investor onboarding",
      "manifestVersion": 3,
      "state": "active"
    }
  ]
}

manifestVersion is pinned at consent — re-publishing a manifest never widens a live connection; new asks require a new consent.

Per-slot status

GET /partner/v1/requests/{requestId}/status

This is the surface to drive your UI from: the connection’s effective state, the manifest’s presentation groups, the parties it asks about and who answers for them, and each slot with its grant status.

{
  "state": "active",
  "groups": [
    { "id": "identity", "label": "Identity", "order": 1 },
    { "id": "family", "label": "Your children", "order": 2 },
    { "id": "company", "label": "Investing company", "order": 3 }
  ],
  "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-…" },
    { "subjectId": "child", "type": "person", "alias": "beef4477-…" }
  ],
  "items": [
    {
      "slotId": "0d4e7a52-1a53-4d69-a9be-52bfa4e0a1c7",
      "label": "Email",
      "group": "identity",
      "kind": "schema",
      "target": "PersonEmail",
      "verbs": [],
      "status": "granted",
      "verification": [
        {
          "method": "email_format",
          "level": "lint",
          "verifiedAt": "2026-08-01T09:12:44Z",
          "version": 1
        }
      ]
    },
    {
      "slotId": "7c2b9e11-30cf-4f2e-9f57-b8a4f7f4f2ad",
      "label": "Proof of address",
      "group": "identity",
      "kind": "schema",
      "target": "PersonAddress",
      "multiple": true,
      "verbs": ["fill", "keep"],
      "status": "pending"
    },
    {
      "slotId": "9e01c4d8-2b1f-4b7e-8c53-6a2f19d5b0aa",
      "label": "Child's name",
      "group": "family",
      "subject": "child",
      "kind": "schema",
      "target": "PersonFullName",
      "verbs": ["fill", "keep"],
      "status": "granted"
    },
    {
      "slotId": "3b8f0c6a-9d2e-4e1b-b1c4-1f7a8e2d9c55",
      "label": "Company details",
      "group": "company",
      "subject": "investing-company",
      "kind": "schema",
      "target": "LegalEntity",
      "verbs": ["fill", "edit", "keep"],
      "status": "pending"
    }
  ]
}

slotId is the canonical address of an item — use it on every other route. kind/target remain for display. Kinds are schema, personal_files and — on a company subject’s slot — entity_files.
verbs say what you may do BEYOND reading. Reading a granted item is what a connection is, so it needs no verb and an empty list is ordinary — the plain ask. fill lets you list the slot’s candidates, attach one, or create a value in it; edit lets you update or delete the granted document on the user’s behalf; keep means your organization holds a copy that survives revocation and receives later versions.
multiple is the slot’s cardinality. false — the default — means the slot holds ONE standing grant: a later fill with a different resource replaces it (the person switching payout accounts is one act, not a revoke-and-reconnect). true means grants accrue — “list all your addresses”. Gate any “add another” affordance in your UI on it; on a subject slot the count is per answering participant (one per child or company, not one per slot).
status is granted or pending — nothing else. pending is deliberately indistinguishable from “the user refused” and from “the user has no such data”. Do not build UI that treats pending as “exists but not yet shared”; render it as not provided with a way to fill it in-app. Status is a live reading, never a latch: a slot goes back to pending when the user deletes the resource that answered it, so re-read it rather than caching the first granted.
subjects is the ask, participants the answer. subjects lists the parties this manifest asks about beyond the account holder, each typed person (with its kinship relation) or company; repeat: true means the user decides how many. participants — absent while nobody is bound — says who is actually cast: one entry per party, each a pairwise alias that is stable across your organization’s connections and meaningless to anyone else. The same alias comes back on every served record and on the subject’s candidates, so you can group a connection’s data by party without ever seeing a vault id. A subject slot stays a single item here whatever its cast: granted means at least one party has answered; who, and how many, is visible through participants and per record when the slot is served. See Subjects: relatives & companies.
verification is assurance metadata about the current version of a granted item — what was checked, how strong, when. Never evidence, present on granted items only, and absent again the moment a new unverified version is written.
state is evaluated at call time against both clocks: the request’s state machine and the terms’ retention window. A connection past its retention reads expired and stops serving immediately.