Integration playbook

This guide takes you from your first API key to live traffic. It gives the order to build in, how to test each stage, and how to know you are finished. For exact fields, endpoints, events and limits, see the partner API reference.

Before you start: read sections 1 to 4 of the API reference so you know which assessment you are running and on which surface.

A product requirement that applies to every integration: a Kirnova result can inform an employment decision but never makes one. There is no pass mark and no automated rejection, and your integration must not add one.

1. Before you start#

1.1 Who sets up what#

You manage your side in the partner settings screen (section 3). For anything on the left, write to team@kirnova.com.

1.2 What to tell Kirnova#

1. Which assessments you need enabled. An account with no assessments configured is refused with TEST_NOT_CONFIGURED. A request for an assessment you do not hold is refused as well. Kirnova never substitutes a different assessment.
2. The web addresses you embed the frame on. If your account has a list, requests from other origins, or with no origin, are refused.

1.3 What you need on your side#

• A server that can keep a secret. Your API key mints launch tokens and reads results. It must never reach a browser, a mobile app or a repository.
• An HTTPS endpoint that accepts a POST, verifies a signature and answers within 30 seconds. A slower response counts as a failed delivery.
• A place to store the session identifier against your own record of the person. The session identifier is the join key for messages, result reads and support requests.

1.4 Where you test#

Test on Kirnova staging, a full copy of the service. Staging serves the API, the frame and the app from one host: https://stage.kirnova.com. Production uses https://api.kirnova.com for the API and https://embed.kirnova.com for the frame.

• Staging key. Write to team@kirnova.com to get one. It starts bi_live_sk_, like a production key, but works only on staging. Tell the environments apart by host, not by key prefix.
• Separate systems. Staging and production have separate databases and signing secrets. Keys, launch tokens and session tokens do not work across them. Configure host, key and webhook address together for each environment.
• Test data only. Staging data is not real customer data and can be reset. Use email addresses your team controls.
• Same limits and behaviour. Your plan's daily sitting limit and per-minute request limit apply on staging. Payloads, errors and signatures match production.

Run phases 1 to 3 in section 4 on staging. Phase 4 is the first time you use the production host.

2. Choose a surface#

You can deliver a sitting in a frame that Kirnova renders inside your product, or you can render the questions yourself and drive the sitting call by call. The availability matrix in the API reference (section 1) shows which surfaces each assessment supports.

If both are available, decide on three points.

1. Who owns the question screens. With the frame, Kirnova owns layout, wording, answer controls, progress, saving and the closing screen. With the machine-driven route you build all of it, including phone support, slow networks and resume.
2. Whether you can host a frame. The frame sets no browser framing restriction. The origins allowed to load it are controlled by your account (section 1.2). Choose the machine-driven route if you cannot host a frame, for example in a native app without a web view or a server-to-server pipeline.
3. Whether you need live progress. On TIGER Core and TIGER Student the frame reports only completion and content height. Kirnova Calling sends no browser messages. For a progress bar in your own interface, use the machine-driven route.

Most partners should use the frame.

3. What you can do in the partner settings screen#

You cannot create your own account, change your plan or limits, change which assessments you can run, or change the list of embed origins. Ask Kirnova for those.

3.1 Branding#

On TIGER Core, TIGER Student and Kirnova Calling, two branding values reach the sitting:

• Light, dark, or follow-the-device theme.
• Your primary colour, which Kirnova lightens or darkens as needed to keep text readable and keeps its hue.

Logo, welcome and completion wording and the switch that hides the Kirnova name apply only to the retired earlier assessment. Second colour, font and button shape do not apply to any current sitting. The document generated for a TIGER sitting uses Kirnova's presentation.

If matching your look is a launch requirement, tell Kirnova before you build.

4. The four phases#

Build in this order. Each phase ends with something you can demonstrate, and the test cases in section 10 close it.

Phase 1 is complete when a person finishes a real sitting and a result is stored, not when a request works in an HTTP client. Phase 2 is complete when your record matches Kirnova's after you deliberately drop a message.

Stored results remain readable to you with no expiry. Keep your own record as the durable copy anyway, so you can reconcile (section 9).

5. The embedded-frame sequence#

CopysequenceDiagram
    autonumber
    participant U as Person's browser (your page)
    participant P as Your server
    participant K as Kirnova API
    participant F as Kirnova frame
    participant W as Your webhook endpoint

    U->>P: "Start my assessment"
    P->>K: POST /api/v1/embed/launch-tokens (Bearer key, identity, test)
    alt Accepted
        K-->>P: 201 {token, expires_at, embed_url, tenant_id, test}
    else Key unknown, revoked, or read-only
        K-->>P: 401 UNAUTHORIZED / 403 FORBIDDEN
    else Assessment not enabled, not on this surface, or account not configured
        K-->>P: 403 TEST_NOT_ENTITLED | TEST_NOT_SERVABLE | TEST_REQUIRED | TEST_NOT_CONFIGURED
    else Name or email missing
        K-->>P: 422 VALIDATION_ERROR
    else Too many requests this minute
        K-->>P: 429 RATE_LIMIT_EXCEEDED + Retry-After
    end
    P-->>U: Render the frame with embed_url
    U->>F: GET the frame address
    alt Launch accepted
        F-->>U: Six-point notice, then the first screen once accepted
    else Token expired, sitting abandoned, origin not allowed
        F-->>U: HTML message card (no status code, no JSON)
    end
    U->>F: Answers, screen by screen (saved as they go)
    F-->>U: postMessage {type: "BI_RESIZE", data: {height}}
    F-->>U: postMessage {type: "BI_ASSESSMENT_COMPLETE", data: {session_id}}
    F-->>U: postMessage {type: "kirnova:assessment:completed", sessionId}
    U->>P: Pass the sessionId to your server
    Note over F,K: The result is scored and stored server-side
    K->>W: POST session.completed (signed)
    alt Your endpoint answers 2xx within 30s
        W-->>K: 200
    else Non-2xx, timeout, or unreachable
        W-->>K: failure, queued for retry (five attempts in total)
    end
    P->>K: GET /api/v1/sessions/{id}/results (reconciliation)
    alt Stored
        K-->>P: 200 {engine, results, ...}
    else Not scored yet
        K-->>P: 409 SCORING_PENDING
    end

1. Your page asks your server to start a sitting. The browser never calls Kirnova, and the key stays on your server.
2. Your server mints a launch token. Both a name and an email address are required. If either is missing, the 422 message names both fields whichever was wrong, so check your own payload instead of parsing the message.
3. Use the returned frame address as is. It carries the token and any display preferences you requested.
4. Render the frame promptly. Tokens are short-lived (section 8.2), so mint immediately before rendering and never in advance.
5. The person sees a six-point notice first. They press "I understand and acknowledge" before any question appears (API reference, section 4.3). Answers save as they go, so a dropped connection or refresh does not lose them.
6. On a TIGER sitting the frame posts two completion messages for the same finish: { type: "BI_ASSESSMENT_COMPLETE", data: { session_id } } and { type: "kirnova:assessment:completed", sessionId }. Act on one only. It also posts { type: "BI_RESIZE", data: { height } } as content height changes. There are no started, page or abandoned messages. Kirnova Calling posts nothing. Check the message origin, and treat messages as signals to update your interface. They carry no answers or scores and can be lost.
7. The signed webhook is your record.
8. Reconcile by reading the result back (section 9).

Code for these branches: a refusal at step 2 for entitlement rather than authentication; a message card instead of a sitting when the token has expired or the origin is not registered; a completion message that never reaches your page; and a webhook that arrives twice.

6. The machine-driven sequence#

You render the questions. Kirnova assembles, validates and scores. After session creation, calls use the session token returned at creation, not your API key. Sending an API key to a page submission is refused.

CopysequenceDiagram
    autonumber
    participant U as Person (your interface)
    participant P as Your server
    participant K as Kirnova API

    P->>K: POST /api/v1/sessions (Bearer key, identity, test)
    alt Accepted
        K-->>P: 201 {session_id, token, current_page: 1, total_pages, questions[]}
    else No usable identity
        K-->>P: 422 RESPONDENT_IDENTITY_REQUIRED
    else Not enabled, not available on this route, or not configured
        K-->>P: 403 TEST_NOT_ENTITLED | 403 or 501 TEST_NOT_SERVABLE | 403 TEST_NOT_CONFIGURED
    else Daily sitting limit reached
        K-->>P: 429 TENANT_DAILY_LIMIT + Retry-After
    end
    loop Each page, in order
        P-->>U: Render that page's questions
        U-->>P: One value, 1 to 5, per question
        P->>K: POST /sessions/{id}/pages/{n} (Bearer session token)
        alt Right page, right count, every id on this page
            K-->>P: 200 {status: "in_progress", current_page: n+1, questions[]}
        else Wrong page number
            K-->>P: 409 SESSION_WRONG_PAGE ("Expected page X, received page Y")
        else Wrong count, unknown id, or repeated id
            K-->>P: 422 VALIDATION_ERROR (field: responses)
        else Session token expired
            K-->>P: 401 UNAUTHORIZED
        end
    end
    P->>K: POST the final page
    alt Scored
        K-->>P: 200 {status: "completed", engine: "tiger", results: {...}}
    else Questions unanswered
        K-->>P: 422 INCOMPLETE_SITTING
    else Storing or scoring failed
        K-->>P: 500 SCORING_FAILED
    end
    Note over P,K: Re-POST the final page to retry a failed completion (idempotent)

Create a sitting

CopyPOST /api/v1/sessions HTTP/1.1
Host: api.kirnova.com
Authorization: Bearer bi_live_sk_9QpX4mZk2LrTvB8sNhCwJd
Content-Type: application/json

{
  "respondent_name": "Meera Raghavan",
  "respondent_email": "meera.raghavan@example.com",
  "external_respondent_id": "LF-CAND-40912",
  "test": "tiger-core",
  "metadata": { "role_req": "LF-REQ-2291" }
}

CopyHTTP/1.1 201 Created

{
  "session_id": "b7d2f118-3a05-4e62-91cc-8ad4e0f37b52",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "status": "initiated",
  "respondent_id": "LF-CAND-40912",
  "current_page": 1,
  "total_pages": 5,
  "section_label": null,
  "page_instruction": null,
  "questions": [
    { "position": 1, "id": "…", "text": "…", "page": 1, "position_on_page": 1 },
    { "position": 2, "id": "…", "text": "…", "page": 1, "position_on_page": 2 }
  ]
}

Submit a page. Answers are an array of objects, not a map.

CopyPOST /api/v1/sessions/b7d2f118-3a05-4e62-91cc-8ad4e0f37b52/pages/1 HTTP/1.1
Host: api.kirnova.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…
Content-Type: application/json

{
  "responses": [
    { "question_id": "…", "value": 4 },
    { "question_id": "…", "value": 2 }
  ]
}

CopyHTTP/1.1 200 OK

{
  "session_id": "b7d2f118-3a05-4e62-91cc-8ad4e0f37b52",
  "status": "in_progress",
  "submitted_page": 1,
  "current_page": 2,
  "total_pages": 5,
  "progress_pct": 20,
  "section_label": null,
  "page_instruction": null,
  "questions": [ "…the next page's questions…" ]
}

The last page returns the finished result:

CopyHTTP/1.1 200 OK

{
  "session_id": "b7d2f118-3a05-4e62-91cc-8ad4e0f37b52",
  "status": "completed",
  "submitted_page": 5,
  "engine": "tiger",
  "results": { "…the body shown in section 7, step 4…" }
}

Rules for this route

1. Submit pages in order. Submitting page 3 when page 2 is expected returns 409 naming both. You cannot skip or go back.
2. Send exactly the number of answers for the page.
3. Use only question identifiers Kirnova sent for that page. Each question can be answered once, and there is no correction path.
4. Every value is a whole number from 1 to 5.
5. Never hardcode a question identifier or page count. Echo back what Kirnova sends, because both vary by assessment and version.
6. section_label and page_instruction are null on every TIGER sitting. Render them conditionally so candidates never see the word "null".
7. The final page is repeatable. If a call times out on the last page, send it again with the same body or an empty one. It re-runs completion and does not reject you.
8. The sitting has a fixed window that starts when the session is created, and nothing refreshes it (API reference, section 14.2). Design the interface so people do not leave mid-sitting and return much later.
9. The create call does not report which assessment it resolved. Send test explicitly every time and record what you sent. If you omit it, it resolves to your account default or is refused.

7. A complete worked example#

This example follows one sitting through the frame. The person, partner and identifiers are invented: Meera Raghavan, a fictional recruiting firm called Larksfield Talent, and TIGER Core.

Structure, field names, status codes and numbers are exact. Prose fields inside a result are illustrative and differ per sitting. Render them; never match on the wording.

Step 0. Provisioning#

Kirnova enables TIGER Core for the Larksfield account and registers the address the frame will be embedded on. Larksfield creates a key in the settings screen and copies the secret when it is shown:

Copybi_live_sk_9QpX4mZk2LrTvB8sNhCwJd

They set the webhook address to https://hooks.larksfield.example/kirnova and subscribe to session.completed. The bi_ prefix is a legacy name kept for compatibility.

Step 1. Your server mints a launch token#

CopyPOST /api/v1/embed/launch-tokens HTTP/1.1
Host: api.kirnova.com
Authorization: Bearer bi_live_sk_9QpX4mZk2LrTvB8sNhCwJd
Content-Type: application/json

{
  "respondent_name": "Meera Raghavan",
  "respondent_email": "meera.raghavan@example.com",
  "external_respondent_id": "LF-CAND-40912",
  "test": "tiger-core",
  "metadata": {
    "role_req": "LF-REQ-2291",
    "stage": "shortlist"
  },
  "embed_options": {
    "theme": "light"
  }
}

CopyHTTP/1.1 201 Created
Content-Type: application/json
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1786312860

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRfaWQiOiIzZjlhMWM3Mi01ZDg0In0.KQ2v8mJ0nQ7YbP4sT1cRlX9fWzE6uH3aG5dNqB0oJyM",
  "expires_at": "2026-08-19T11:05:00.000Z",
  "embed_url": "https://embed.kirnova.com/embed/v1/launch?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRfaWQiOiIzZjlhMWM3Mi01ZDg0In0.KQ2v8mJ0nQ7YbP4sT1cRlX9fWzE6uH3aG5dNqB0oJyM&theme=light",
  "tenant_id": "3f9a1c72-5d84-4b1e-9e2f-7c0a6b83d411",
  "test": "tiger-core"
}

metadata is yours. Kirnova stores it unread and returns it on the webhook, the read-back and the batch listing. Put your requisition, stage and candidate key there to simplify reconciliation.

The response test field echoes the assessment that was resolved. Record it against the candidate.

Step 2. Your page renders the frame#

Copy<iframe
  src="https://embed.kirnova.com/embed/v1/launch?token=…&theme=light"
  title="Assessment"
  width="100%"
  height="900"
  style="border:0"
></iframe>

Start with a generous height. TIGER sittings send BI_RESIZE messages as content height changes, so you can resize from them. Kirnova Calling sends none, so choose a height that works on a phone or let the frame fill the viewport.

Display preferences travel in the address and are not signed. Treat them as preferences, and do not make anything important depend on them.

Step 3. Your page listens for completion#

Copy<script>
  const KIRNOVA_FRAME_ORIGIN = "https://embed.kirnova.com";

  window.addEventListener("message", (event) => {
    if (event.origin !== KIRNOVA_FRAME_ORIGIN) return;
    const msg = event.data;
    if (!msg || msg.type !== "kirnova:assessment:completed") return;

    // msg.sessionId is a top-level camelCase field. There is no msg.data wrapper
    // and no scores or answers. A BI_ASSESSMENT_COMPLETE message for the same
    // finish arrives just before this one; this snippet ignores it on purpose.
    fetch("/internal/kirnova/sitting-finished", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ sessionId: msg.sessionId }),
    });

    showThankYouScreen();
  });
</script>

This applies to TIGER Core and TIGER Student. Kirnova Calling sends no browser message, but its result still reaches you by the signed session.completed webhook and by read-back. The retired earlier assessment used a different message family; see the API reference (section 5).

Step 4. The result arrives at your endpoint#

CopyPOST /kirnova HTTP/1.1
Host: hooks.larksfield.example
Content-Type: application/json
x-bi-webhook-event: session.completed
x-bi-webhook-signature: sha256=6f1b0c9d4a7e2f5813c6b9d0a24e7f31c58d92b6e04a7cf13d8e5b207a94c6f1
x-bi-webhook-timestamp: 1786312931

{
  "event": "session.completed",
  "timestamp": "2026-08-19T11:42:11.004Z",
  "tenant_id": "3f9a1c72-5d84-4b1e-9e2f-7c0a6b83d411",
  "data": {
    "session_id": "a1c47e02-9b3d-4c6f-8f21-5d0e7a94b6c8",
    "respondent_name": "Meera Raghavan",
    "respondent_email": "meera.raghavan@example.com",
    "external_respondent_id": "LF-CAND-40912",
    "metadata": { "role_req": "LF-REQ-2291", "stage": "shortlist" },
    "completed_at": "2026-08-19T11:42:08.311Z",
    "test": "tiger-core",
    "result": {
      "engine": "tiger",
      "tier": "core",
      "contract_version": "tiger-report-v1",
      "bar_description": "…sentence describing what the range means…",
      "dimensions": [
        { "name": "Trust", "value": 68,
          "bar": { "lower": 58, "estimate": 68, "higher": 78, "axisMin": 1, "axisMax": 100 },
          "presentation": "two_sided", "meaningLine": "…" },
        { "name": "Influence", "value": 44,
          "bar": { "lower": 34, "estimate": 44, "higher": 54, "axisMin": 1, "axisMax": 100 },
          "presentation": "two_sided", "meaningLine": "…" },
        { "name": "Grit", "value": 78,
          "bar": { "lower": 70, "estimate": 78, "higher": 86, "axisMin": 1, "axisMax": 100 },
          "presentation": "two_sided", "meaningLine": "…" },
        { "name": "Execution", "value": 52,
          "bar": { "lower": 42, "estimate": 52, "higher": 62, "axisMin": 1, "axisMax": 100 },
          "presentation": "two_sided", "meaningLine": "…" },
        { "name": "Resilience", "value": 39,
          "bar": { "lower": 30, "estimate": 39, "higher": 48, "axisMin": 1, "axisMax": 100 },
          "presentation": "two_sided", "meaningLine": "…" }
      ],
      "strengths": {
        "framing": "Strongest within this person's own profile. This compares them to themselves, not to other people, and it is an ordering, not a measured difference between their dimensions.",
        "dimensions": ["Grit"]
      },
      "to_probe": {
        "framing": "Lowest within this profile, worth probing in an interview. Again an ordering within this person, not a measured gap.",
        "dimensions": ["Resilience", "Influence"]
      },
      "adaptive_load_reading": "…sentence about whether their answers shifted under demand…",
      "openness_reading": { "title": "…", "body": "…" },
      "quality_banner": null,
      "interests": null,
      "onet_interests": null
    }
  }
}

Points to note in this body:

• strengths.dimensions and to_probe.dimensions are arrays of dimension names (["Grit"]), not objects. Look up the full reading in the top-level dimensions array by name.
• The signature header is prefixed sha256=. Compare against the full header value, not a bare hex digest.
• On the webhook, the result is under data.result (singular). On the read-back API it is under results (plural).
• Some names are snake_case and the fields inside bar are camelCase. Copy the names exactly and do not normalise them.
• quality_banner is null when the sitting is decision-grade. When it is not null, it holds a sentence saying the result should not be used for a decision. Show it wherever you show the scores, with the same words for the candidate and the hirer.
• Always show each value with its range. Do not show a value alone, order people on the values alone, or derive a threshold from them. If two people's ranges overlap, the instrument does not separate them. See Reading a result.
• This example omits fields added later. A current result also carries a one-word "confidence" (High, Moderate or Low) on each dimension, and the keys what_changed, role_families and interests_boundary. The API reference (section 9.2) defines them.

Step 5. Verify the signature#

The signature covers the raw request body exactly as received. It does not cover the timestamp header, the event header or the URL. Read the raw bytes before any JSON middleware parses them. Re-serialising the parsed object is the most common cause of a signature that never matches.

Copyconst crypto = require("crypto");

function verifyKirnovaWebhook(rawBody, signatureHeader, secret) {
  if (typeof signatureHeader !== "string") return false;

  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)          // the raw body as received: a Buffer or the exact string
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureHeader, "utf8");
  if (a.length !== b.length) return false;   // timingSafeEqual throws on a length mismatch
  return crypto.timingSafeEqual(a, b);
}

An Express endpoint, using express.raw rather than express.json:

Copyapp.post("/kirnova",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifyKirnovaWebhook(
      req.body,
      req.get("x-bi-webhook-signature"),
      process.env.KIRNOVA_WEBHOOK_SECRET,
    );
    if (!ok) return res.status(401).end();

    const payload = JSON.parse(req.body.toString("utf8"));
    res.status(200).end();   // answer first
    enqueue(payload);        // process afterwards
  });

Answer with a 2xx first and process afterwards. A non-2xx response, or one slower than 30 seconds, counts as a failed delivery and starts the retry schedule (API reference, section 7).

Step 6. Read the result back#

Use your API key. A read-only key is enough.

CopyGET /api/v1/sessions/a1c47e02-9b3d-4c6f-8f21-5d0e7a94b6c8/results HTTP/1.1
Host: api.kirnova.com
Authorization: Bearer bi_live_sk_9QpX4mZk2LrTvB8sNhCwJd

CopyHTTP/1.1 200 OK
Content-Type: application/json

{
  "session_id": "a1c47e02-9b3d-4c6f-8f21-5d0e7a94b6c8",
  "status": "completed",
  "respondent_name": "Meera Raghavan",
  "respondent_email": "meera.raghavan@example.com",
  "external_respondent_id": "LF-CAND-40912",
  "metadata": { "role_req": "LF-REQ-2291", "stage": "shortlist" },
  "completed_at": "2026-08-19T11:42:08.311Z",
  "result_updated_at": "2026-08-19T11:42:08.311Z",
  "ai_enrichment_status": null,
  "engine": "tiger",
  "results": {
    "engine": "tiger",
    "tier": "core",
    "contract_version": "tiger-report-v1",
    "…": "the same body as the webhook's data.result",
    "pdf": { "available": false, "url": null, "expires_at": null }
  }
}

Branch on the top-level engine field, not on which keys are present. It tells you the shape of results. Ignore fields you do not recognise, because new fields are added additively.

A TIGER result read also carries delivered_at and updated_at. If the person's TIGER has been read again since delivery, and consent to share with you is granted, results is the newer reading, updated_at is set and results.what_changed explains the difference. The signed completion message always carries the reading as first delivered. The API reference (section 9.2, "Updated results") has the detail.

If scoring has not finished, the call returns 409 SCORING_PENDING. Wait and retry.

Step 7. Fetch the document#

CopyGET /api/v1/sessions/a1c47e02-9b3d-4c6f-8f21-5d0e7a94b6c8/pdf HTTP/1.1
Host: api.kirnova.com
Authorization: Bearer bi_live_sk_9QpX4mZk2LrTvB8sNhCwJd

This route streams the file. It returns application/pdf bytes or a redirect to storage, which your HTTP client should follow. Add ?disposition=inline to display the file instead of downloading it.

For a TIGER sitting, your first request produces the document, so the first call takes longer and the pdf block reports available: false until then. If you subscribe to pdf.ready, the message arrives when the document is produced. When the person's TIGER has been read again and consent to share with you is granted, the TIGER document shows the current reading and opens with a "what changed" block, as the result routes do.

8. Handling failures#

8.1 The person abandons#

Answers stay saved. Nothing is scored, so no result exists and no completion is sent.

You will see no completion message, no session.completed, and a read-back that returns 409 SCORING_PENDING. In your settings screen, an unfinished frame sitting appears under All. The In progress filter covers only machine-driven sittings with at least one submitted page.

Detect abandonment on your own clock, for example an in-progress sitting older than your staleness limit. A TIGER sitting in the frame is never recorded as abandoned, so no notification is sent. To resume, start the person again with a fresh token. On the machine-driven route you can close a sitting yourself (API reference, section 6.5), which sends session.abandoned. The first attempt is made when you close the sitting, and a failed attempt is retried by the daily sweep.

8.2 The person refreshes or the connection drops#

Nothing is lost. Answers are held server-side, and the same sitting is returned with the same questions. On the machine-driven route, the server still expects the next page in sequence, so request it and continue.

Within the launch token's 5-minute window, presenting the same address again returns the same sitting. After that window the address is refused as an expired launch token, which is the usual case because sittings take longer than the token lives. Mint a fresh launch token for the same person. They resume the same sitting with the same questions and all earlier answers.

Note: a fresh token creates a new session identifier for the same sitting. The completion message, webhook and stored result arrive under the newest identifier, and the earlier one stays in progress and never completes. Store every identifier you mint for a person against your own record, and reconcile on the one that completes.

Do not build a "restart" button that discards the person's place. Minting a fresh token is the recovery.

8.3 The person returns after the window has closed#

The sitting window lapses. The frame shows a message card saying the session expired, and machine-driven page submissions return 401. Nothing extends the window.

Mint a fresh token so the person can sit again. On the machine-driven route, a lapsed sitting cannot be recovered. Design the experience so it rarely happens: one continuous session, no overnight pauses.

8.4 Your webhook endpoint is down#

A failed attempt is queued for retry. There are five attempts in total, on the schedule in the API reference (section 7). The second attempt is about a minute after the first. Later attempts are sent when due, and a daily sweep is the safety net, so on low-traffic accounts a later attempt can wait until the next day. After the fifth attempt, delivery stops. Do not treat retries as a delivery guarantee.

A silent endpoint looks like a quiet week. Alert on the absence of deliveries, and run the reconciliation sweep (section 9) on a schedule.

8.5 The browser message never arrives#

The person may have closed the tab, a browser extension may have interfered, or your listener may expect the wrong shape. Treat the message as a signal to update your interface only. The webhook and the read-back are your record. If your page must advance, poll your server for the result every few seconds while the page is open.

9. Reconciliation#

A browser message can be lost, and a webhook can arrive twice. Reconciliation makes both harmless.

1. Use the session identifier as your idempotency key. Store records keyed on session_id plus event name. For a repeated session.completed on a session you already hold, update in place and do nothing else: no second notification, no second charge, no second result row.
2. Verify before you read. Verify the signature before looking at the payload and drop anything that fails. A valid body that arrives twice is a duplicate. A body that fails verification is not from Kirnova.
3. Reconcile on a schedule. For every sitting you started without a result, ask Kirnova:
   • GET /api/v1/sessions/{id}/results for a specific person. 200 means the result exists and you missed it. 409 SCORING_PENDING means there is nothing to miss.
   • GET /api/v1/tenants/{tenant_id}/results for a sweep. It lists everything completed in a date range, live sittings by default. The start of the range is required, and paging uses limit and offset. The response carries count, the requested page and the rows.

Daily sweep. Once a day, request everything completed since your last successful sweep, minus a safety margin. For each row you do not already hold, treat it as if the webhook had just arrived. This closes every delivery failure in section 8.4.

A row whose result cannot be read is marked unreadable instead of failing the whole page. Skip those rows and report them to Kirnova (section 13). Because your access to stored results does not lapse, a sweep that was broken for a fortnight can still recover everything it missed.

10. Test plan#

Run every case on Kirnova staging, using email addresses your team controls. A partner who passes all 23 cases has a working integration. A partner who passes only cases 1 to 7 has a demo.

Do not write tests that wait for these, which the cases deliberately do not assert:

• An abandonment notification for a TIGER frame sitting. None is sent.
• The behaviour of a reused launch address after the sitting has finished.
• Recovery of a machine-driven sitting whose window has lapsed. No route offers it.

11. Production checklist#

12. Troubleshooting#

13. Contacting Kirnova#

Write to team@kirnova.com and include:

1. The session identifier. For several, send a list. If you have none, send the respondent's email address and the approximate time.
2. When it happened, with the time zone.
3. The environment (staging or production) and the host you called.
4. The exact request and response, including status code and error code, with your API key and any tokens removed.
5. What you expected, in one sentence.

For a webhook problem, add the event header, the timestamp header, and whether your endpoint answered and with what.

Never send a screenshot of a key or token. If you think a key is exposed, revoke it in your settings screen first. Revocation is immediate and does not need Kirnova.