> ## Documentation Index
> Fetch the complete documentation index at: https://developers-test.idunox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Flow

> The main implementation sequence for the Health Yourself partner integration (lab environment).

<Note>
  **Lab environment.** API base URL: **`https://api-test.idunox.com`**. Send your API key as **`X-Api-Key`** (or `Authorization: Bearer` on direct Cloud Run URLs). Production docs live at `api.idunox.com` (separate Mintlify project).
</Note>

Use this page as the primary implementation path. The detailed pages linked from each step are supporting references.

## Before you start

During onboarding, Idunox provides:

| Item                    | How it is used                                                        |
| ----------------------- | --------------------------------------------------------------------- |
| API key                 | Sent as **`X-Api-Key`** on **`https://api-test.idunox.com`** (lab)    |
| Partner credential UUID | Sent as `partnerId` in every submission body (must match the API key) |
| Base URL                | **`https://api-test.idunox.com`** (lab API — not the docs site)       |

If you do not have credentials yet, email `partner@idunox.com`.

## 1) Prepare Health Yourself data

Collect questionnaire and blood data in your intake UX, then **map** to canonical JSON in your backend:

| Data                   | Canonical location                                                            |
| ---------------------- | ----------------------------------------------------------------------------- |
| 36 questionnaire items | `subject.*` (see [Canonical submission JSON](/platform/canonical-submission)) |
| 14 blood analytes      | `markers[]` with codes such as `ALT`, `HBA1C_MMOL_MOL`                        |
| Lab reference ranges   | `sourceMetadata.markerRanges` (structured `unit`, `lowerBound`, `upperBound`) |
| Intake timestamp       | `sourceMetadata.sourceTimestamp`                                              |
| Wellbeing areas        | `options.requestedOutcomes` (`wellbeing.cardiovascular`, etc.)                |
| Report outputs         | `options.requestedOutputs` (`inference_score_v1`, `json`, `html`, …)          |

The [Input Data Preparation Guide](/api-reference/introduction) remains the source of truth for **what to ask** end consumers (wording, conditionals, accepted intake values). The [Canonical submission JSON](/platform/canonical-submission) page defines **how to encode** that data for the API.

## 2) Authenticate

Use **`X-Api-Key`** on the lab API hostname (or Bearer on direct Cloud Run if instructed):

```http theme={null}
X-Api-Key: <your-api-key>
```

Validate your credentials before sending submissions:

```bash theme={null}
curl -H "X-Api-Key: <your-api-key>" \
     https://api-test.idunox.com/v1/partner-auth-probe
```

A valid credential returns `204 No Content`. See [Authentication](/platform/authentication) for details.

## 3) Submit one complete payload

Submit canonical JSON to `POST /v1/submissions` with write headers:

```bash theme={null}
curl -X POST https://api-test.idunox.com/v1/submissions \
     -H "X-Api-Key: <your-api-key>" \
     -H "x-correlation-id: <request-correlation-id>" \
     -H "Idempotency-Key: <unique-key>" \
     -H "Content-Type: application/json" \
     --data @submission.json
```

`submission.json` must include `schemaVersion`, `partnerId`, `partnerSubmissionId`, `partnerSubjectId`, `subject`, `markers`, and `options` as described in [Create Submissions](/api-reference/endpoint/submissions).

A successful submission returns `202 Accepted` with a `submissionId`. Store this ID.

## 4) Wait for processing

After submission, use either polling or webhooks.

| Option                 | Use when                                    | Next action                                                             |
| ---------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
| Poll submission status | You want a simple client-driven integration | Call `GET /v1/submissions/{submissionId}` until `status` is `completed` |
| Receive webhook        | You have a registered HTTPS callback URL    | Wait for `result.ready`, then read `resultId` from the webhook body     |

Polling example:

```bash theme={null}
curl -H "X-Api-Key: <your-api-key>" \
     https://api-test.idunox.com/v1/submissions/<submissionId>
```

See [Get submission](/api-reference/endpoint/get_submissions) and [Webhook: result.ready](/api-reference/endpoint/webhook).

## 5) Retrieve the result

When processing is complete, retrieve the result with `resultId`:

```bash theme={null}
curl -H "X-Api-Key: <your-api-key>" \
     https://api-test.idunox.com/v1/results/<resultId>
```

The response contains **`outcome`** (primary) and optionally **`outcomes[]`** — one partner-safe summary per requested wellbeing area, plus signed **`artifacts`** download URLs when `json` / `html` / `pdf` were requested.

See [Get result](/api-reference/endpoint/results) and [Outcomes model](/platform/assessments-model).

## Supporting references

<CardGroup cols={2}>
  <Card title="Input Data Guide" icon="database" href="/api-reference/introduction">
    Intake questions, blood panel table, and conditional trees.
  </Card>

  <Card title="Canonical submission" icon="file-code" href="/platform/canonical-submission">
    Q→canonical mapping, marker codes, and validation rules.
  </Card>

  <Card title="Create Submissions" icon="paper-plane" href="/api-reference/endpoint/submissions">
    Full POST body example and field reference.
  </Card>

  <Card title="Get Result" icon="chart-line" href="/api-reference/endpoint/results">
    Completed result with outcomes and artifacts.
  </Card>
</CardGroup>