Institution API, webhooks & widget

Authentication

Every request carries your institution API key in the X-Kybex-Key header. Keys are long-lived, scoped to one institution, and can be rotated from the portal. Treat a key as a secret: call the API from your server, never from a browser.

curl https://kybex.io/api/public/v1/shares \
  -H "X-Kybex-Key: kbx_live_xxxxxxxxxxxxxxxx"

GET /api/public/v1/shares

Returns every share your institution has received, newest first.

{
  "institution": { "id": "uuid", "name": "Kuda Microfinance Bank" },
  "shares": [
    {
      "submission_id": "uuid",
      "share_token": "a1b2c3…",
      "status": "viewed",
      "channel": "link",
      "sent_at": "2026-09-14T09:12:04Z",
      "viewed_at": "2026-09-14T10:41:55Z",
      "business": { "id": "uuid", "name": "Lumen Logistics Ltd", "country": "Nigeria" },
      "data_points": [
        { "field_key": "legal_name", "label": "Legal name",
          "value": "Lumen Logistics Limited", "provenance": "confirmed" }
      ],
      "documents": [
        { "id": "uuid", "name": "certificate-of-incorporation.pdf",
          "doc_type": "certificate_of_incorporation",
          "sha256": "9f2c…", "version": 2,
          "expires_at": null, "created_at": "2026-08-02T11:20:00Z" }
      ]
    }
  ]
}

provenance is one of self_declared, ai_extracted_unconfirmed or confirmed. Only confirmed values have been reviewed by the business against the source document. Kybex does not verify contents.

GET /api/public/v1/shares/:share_token

Returns one share, including the structured data and document metadata included in it. Useful when a webhook has just told you a share arrived.

GET /api/public/v1/documents/:id

Returns a short-lived download URL for one document, provided it belongs to a share you received. Pass share_token as a query parameter.

{ "url": "https://…signed…", "expires_in": 300 }

Webhook events

Set a webhook URL in the portal. Kybex POSTs a JSON body with an event and a data object. Respond 2xx within ten seconds; non-2xx responses are retried with backoff.

share.received      a business shared with you
share.updated       the business replaced a document or field in an existing share
document.renewed    a new version of a previously shared document was uploaded

{
  "event": "share.received",
  "sent_at": "2026-09-14T09:12:04Z",
  "data": { "submission_id": "uuid", "share_token": "a1b2c3…",
            "business": { "id": "uuid", "name": "Lumen Logistics Ltd" } }
}

Connect Widget

Drop the widget into your own onboarding page. The business is recognised with a lightweight one-time code — not a full login — picks what to share, and the widget hands your page the resulting share token so you can pull the data server-side.

<iframe
  src="https://kybex.io/widget?institution=INSTITUTION_ID"
  style="width:100%;height:560px;border:0;border-radius:18px"
  title="Share business documents with Kybex"></iframe>

<script>
  window.addEventListener("message", (event) => {
    if (event.origin !== "https://kybex.io") return;
    if (event.data?.type === "kybex:share_completed") {
      // event.data.share_token — pull the share server-side with your API key
    }
  });
</script>

Sample integration

// Node — fetch new shares and store them
const res = await fetch("https://kybex.io/api/public/v1/shares", {
  headers: { "X-Kybex-Key": process.env.KYBEX_KEY },
});
if (!res.ok) throw new Error(await res.text());
const { shares } = await res.json();

for (const share of shares) {
  await db.applications.upsert({
    externalId: share.submission_id,
    businessName: share.business.name,
    fields: Object.fromEntries(share.data_points.map((d) => [d.field_key, d.value])),
    documents: share.documents,
  });
}

Errors

401 missing or unknown API key · 404 share not found or not shared with you · 429 rate limited · 5xx retry with backoff.