Developers

Institution API, webhooks & widget

Everything an institution needs to pull Kybex shares into its own systems, and to ask a business for a pack without anyone opening the dashboard. Your API key is in the institution portal under API & webhooks.

Ask a business for a pack

The whole point of Kybex is that a business does not re-key the same documents for the fourth time, and that only pays off when the request and the result land inside your own system. The business fills only the gap between what you asked for and what it already holds, and does not need a Kybex account to start.

curl -X POST https://kybex.io/api/public/v1/requests \
  -H "X-Kybex-Key: kbx_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "ng_corporate_account",
    "invite_email": "finance@acme.test",
    "invite_name": "Acme Logistics Ltd",
    "message": "For your corporate account application."
  }'

Calling it twice with the same email and template returns the open request rather than creating a second one — a retry after a timeout should not produce two requests to the same business. Then poll GET /api/public/v1/requests/:id for its status item by item, and GET /api/public/v1/requests/:id/bundle once it is fulfilled. Or register a webhook and skip the polling.

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 person (a business or an individual) is recognised with a lightweight one-time code — not a full login — sees what you are asking for and why, ticks what they will share, and the widget tells your page when it is done. What it sends is a submission id, never the share token: a token opens the pack, and the page an iframe sits in is not authenticated. Resolve the id server-side with your API key.

Register the address of each page that will embed it on the API & webhooks page in your account. The widget is shown only on registered pages and posts only to them. A share made through it lasts 7 days, can be revoked by the person at any time, and every access is logged. Optional address parameters: pack (a checklist key or id), purpose (shown to the person, 200 characters) and reference (your own case number, stored with the share, 120 characters).

<iframe
  id="kybex-connect"
  src="https://kybex.io/widget?institution=INSTITUTION_ID&pack=ng_corporate_account&purpose=Opening%20a%20business%20account&reference=APP-2041"
  style="width:100%;height:560px;border:0;border-radius:18px"
  referrerpolicy="strict-origin-when-cross-origin"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
  title="Share documents with Kybex"></iframe>

<script>
  window.addEventListener("message", (event) => {
    if (event.origin !== "https://kybex.io") return;
    if (event.source !== document.getElementById("kybex-connect").contentWindow) return;
    if (event.data?.type === "kybex:share_completed") {
      // event.data.submission_id — resolve it server-side with your API key.
      // The widget deliberately does NOT send the share token: a token is the
      // credential for reading the pack, and postMessage would hand it to
      // whatever page the iframe sits in.
      //   GET /api/public/v1/submissions/{submission_id}
    }
  });
</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.