Skip to main content
POST
/
v1
/
submissions
curl --request POST \ --url https://api.idunox.com/v1/submissions \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: <idempotency-key>' \ --header 'X-Api-Key: <api-key>' \ --header 'x-correlation-id: <x-correlation-id>' \ --data ' { "schemaVersion": "canonical_submission_v1", "partnerId": "11111111-1111-4111-8111-111111111111", "partnerSubmissionId": "hy-sub-0001", "partnerSubjectId": "hy-pt-0001", "sourceMetadata": { "sourceSystem": "health-yourself-frontend", "sourceTimestamp": "2026-04-20T09:00:00.000Z", "labName": "Partner Central Lab", "facilityId": "FAC-001", "markerRanges": { "ALBUMIN": { "unit": "g/L", "lowerBound": 35, "upperBound": 50 }, "ALT": { "unit": "U/L", "lowerBound": 7, "upperBound": 56 }, "ALP": { "unit": "U/L", "lowerBound": 44, "upperBound": 147 }, "AST": { "unit": "U/L", "lowerBound": 10, "upperBound": 40 }, "CALCIUM": { "unit": "mmol/L", "lowerBound": 2.1, "upperBound": 2.55 }, "CHOL": { "unit": "mmol/L", "lowerBound": 0.5, "upperBound": 5.2 }, "CYSTATIN_C": { "unit": "mg/L", "lowerBound": 0.61, "upperBound": 0.95 }, "GGT": { "unit": "U/L", "lowerBound": 9, "upperBound": 48 }, "HDL": { "unit": "mmol/L", "lowerBound": 1, "upperBound": 4.65 }, "CRP": { "unit": "mg/L", "lowerBound": 0.08, "upperBound": 3 }, "LDL": { "unit": "mmol/L", "lowerBound": 0.26, "upperBound": 3.3 }, "PHOSPHATE": { "unit": "mmol/L", "lowerBound": 0.8, "upperBound": 1.5 }, "URATE": { "unit": "µmol/L", "lowerBound": 155, "upperBound": 357 }, "HBA1C_MMOL_MOL": { "unit": "mmol/mol", "lowerBound": 20, "upperBound": 41 } } }, "subject": { "demographics": { "sexAtBirth": "female", "ageYears": 52 }, "measurements": { "weightKg": 72.4, "heightCm": 168 }, "history": { "overallHealth": "good", "smoking": { "status": "former", "pastFrequency": "heavy", "pastCigsPerDay": 12, "startAge": 19, "stopAge": 41 }, "conditions": { "hasDiabetes": false, "hasDementia": false, "hasCardioCerebrovascular": false, "hasLungCancer": false, "hasKidneyDisease": false }, "medications": { "takesRegularMedication": true } }, "familyHistory": { "father": { "aliveStatus": "deceased", "deathAge": 73, "conditions": [ "alzheimer_disease", "diabetes_mellitus", "cardiovascular_disease", "hypertension" ] }, "mother": { "aliveStatus": "alive", "currentAge": 79, "conditions": [ "hypertension", "diabetes_mellitus" ] } } }, "markers": [ { "code": "ALBUMIN", "value": 42, "unit": "g/L" }, { "code": "ALT", "value": 28, "unit": "U/L" }, { "code": "ALP", "value": 85, "unit": "U/L" }, { "code": "AST", "value": 24, "unit": "U/L" }, { "code": "CALCIUM", "value": 2.35, "unit": "mmol/L" }, { "code": "CHOL", "value": 5.2, "unit": "mmol/L" }, { "code": "CYSTATIN_C", "value": 0.95, "unit": "mg/L" }, { "code": "GGT", "value": 32, "unit": "U/L" }, { "code": "HDL", "value": 1.4, "unit": "mmol/L" }, { "code": "CRP", "value": 1.2, "unit": "mg/L" }, { "code": "LDL", "value": 3.1, "unit": "mmol/L" }, { "code": "PHOSPHATE", "value": 1.1, "unit": "mmol/L" }, { "code": "URATE", "value": 320, "unit": "µmol/L" }, { "code": "HBA1C_MMOL_MOL", "value": 38, "unit": "mmol/mol" } ], "options": { "requestedOutputs": [ "inference_score_v1", "json", "html" ], "requestedOutcomes": [ "wellbeing.cardiovascular", "wellbeing.cognitive", "wellbeing.renal", "wellbeing.respiratory" ] } } '
{
  "submissionId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "jobId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "partnerSubmissionId": "partner-ext-sub-0001",
  "partnerSubjectId": "partner-ext-pt-0001",
  "status": "accepted"
}
Submit a de-identified canonical Type A JSON body (canonical_submission_v1). Map your intake questionnaire and blood panel in your backend before calling this endpoint — see Canonical submission JSON and the Input Data Preparation Guide.

​
Request requirements

  • partnerId must equal the UUID of the PartnerCredential tied to your API key.
  • Include a non-empty markers[] array with all 14 Health Yourself blood marker codes.
  • Structure questionnaire data under subject (not markers.healthQuestionnaireMarkers).
  • Send options.requestedOutputs (required) and options.requestedOutcomes for the four HY wellbeing areas.
  • Provide sourceMetadata.sourceTimestamp for when the intake was completed; optional sourceMetadata.markerRanges for lab reference intervals.
  • On every POST, send non-empty x-correlation-id and Idempotency-Key headers.
The API validates the canonical schema at request time (types, enums, smoking/family conditionals, and the 14-marker panel). Rejected requests return 400 with field-level details — see Errors.

​
Top-level field reference

FieldRequiredNotes
schemaVersionYescanonical_submission_v1
partnerIdYesPartner credential UUID
partnerSubmissionIdYesYour unique reference (max 512 characters)
partnerSubjectIdYesDe-identified subject reference
subjectYesDemographics, measurements, history, family history
markersYes14 blood observations (code, value, unit)
optionsYesrequestedOutputs + requestedOutcomes
sourceMetadataRecommendedsourceTimestamp, markerRanges, lab metadata

​
Health Yourself request example

curl -X POST "https://api.idunox.com/v1/submissions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "x-correlation-id: hy-2026-05-25-001" \
  -H "Idempotency-Key: hy-submission-0001" \
  -d @submission.json
submission.json: 
{
  "schemaVersion": "canonical_submission_v1",
  "partnerId": "11111111-1111-4111-8111-111111111111",
  "partnerSubmissionId": "hy-sub-0001",
  "partnerSubjectId": "hy-pt-0001",
  "sourceMetadata": {
    "sourceSystem": "health-yourself-frontend",
    "sourceTimestamp": "2026-04-20T09:00:00.000Z",
    "labName": "Partner Central Lab",
    "facilityId": "FAC-001",
    "markerRanges": {
      "ALBUMIN": { "unit": "g/L", "lowerBound": 35, "upperBound": 50 },
      "ALT": { "unit": "U/L", "lowerBound": 7, "upperBound": 56 },
      "ALP": { "unit": "U/L", "lowerBound": 44, "upperBound": 147 },
      "AST": { "unit": "U/L", "lowerBound": 10, "upperBound": 40 },
      "CALCIUM": { "unit": "mmol/L", "lowerBound": 2.1, "upperBound": 2.55 },
      "CHOL": { "unit": "mmol/L", "lowerBound": 0.5, "upperBound": 5.2 },
      "CYSTATIN_C": { "unit": "mg/L", "lowerBound": 0.61, "upperBound": 0.95 },
      "GGT": { "unit": "U/L", "lowerBound": 9, "upperBound": 48 },
      "HDL": { "unit": "mmol/L", "lowerBound": 1.0, "upperBound": 4.65 },
      "CRP": { "unit": "mg/L", "lowerBound": 0.08, "upperBound": 3.0 },
      "LDL": { "unit": "mmol/L", "lowerBound": 0.26, "upperBound": 3.3 },
      "PHOSPHATE": { "unit": "mmol/L", "lowerBound": 0.8, "upperBound": 1.5 },
      "URATE": { "unit": "µmol/L", "lowerBound": 155, "upperBound": 357 },
      "HBA1C_MMOL_MOL": { "unit": "mmol/mol", "lowerBound": 20, "upperBound": 41 }
    }
  },
  "subject": {
    "demographics": {
      "sexAtBirth": "female",
      "ageYears": 52
    },
    "measurements": {
      "weightKg": 72.4,
      "heightCm": 168
    },
    "history": {
      "overallHealth": "good",
      "smoking": {
        "status": "former",
        "pastFrequency": "heavy",
        "pastCigsPerDay": 12,
        "startAge": 19,
        "stopAge": 41
      },
      "conditions": {
        "hasDiabetes": false,
        "hasDementia": false,
        "hasCardioCerebrovascular": false,
        "hasLungCancer": false,
        "hasKidneyDisease": false
      },
      "medications": {
        "takesRegularMedication": true
      }
    },
    "familyHistory": {
      "father": {
        "aliveStatus": "deceased",
        "deathAge": 73,
        "conditions": [
          "alzheimer_disease",
          "diabetes_mellitus",
          "cardiovascular_disease",
          "hypertension"
        ]
      },
      "mother": {
        "aliveStatus": "alive",
        "currentAge": 79,
        "conditions": ["hypertension", "diabetes_mellitus"]
      }
    }
  },
  "markers": [
    { "code": "ALBUMIN", "value": 42, "unit": "g/L" },
    { "code": "ALT", "value": 28, "unit": "U/L" },
    { "code": "ALP", "value": 85, "unit": "U/L" },
    { "code": "AST", "value": 24, "unit": "U/L" },
    { "code": "CALCIUM", "value": 2.35, "unit": "mmol/L" },
    { "code": "CHOL", "value": 5.2, "unit": "mmol/L" },
    { "code": "CYSTATIN_C", "value": 0.95, "unit": "mg/L" },
    { "code": "GGT", "value": 32, "unit": "U/L" },
    { "code": "HDL", "value": 1.4, "unit": "mmol/L" },
    { "code": "CRP", "value": 1.2, "unit": "mg/L" },
    { "code": "LDL", "value": 3.1, "unit": "mmol/L" },
    { "code": "PHOSPHATE", "value": 1.1, "unit": "mmol/L" },
    { "code": "URATE", "value": 320, "unit": "µmol/L" },
    { "code": "HBA1C_MMOL_MOL", "value": 38, "unit": "mmol/mol" }
  ],
  "options": {
    "requestedOutputs": ["inference_score_v1", "json", "html"],
    "requestedOutcomes": [
      "wellbeing.cardiovascular",
      "wellbeing.cognitive",
      "wellbeing.renal",
      "wellbeing.respiratory"
    ]
  }
}

​
Accepted response (202)

{
  "submissionId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "jobId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "partnerSubmissionId": "hy-sub-0001",
  "partnerSubjectId": "hy-pt-0001",
  "status": "accepted",
  "receivedAt": "2026-04-20T09:00:02.000Z"
}
Store submissionId. Poll GET /v1/submissions/{submissionId} or wait for the result.ready webhook, then call GET /v1/results/{resultId}.

Authorizations

​
X-Api-Key
string
header
required

Plaintext API key issued for the tenant (stored hashed server-side).

Headers

​
x-correlation-id
string
required

Client-supplied correlation id for writes; bound to error logs and payloads where applicable.

Minimum string length: 1
​
Idempotency-Key
string
required

Client key for at-most-once submit semantics (24h scope). Reuse with the same body returns the same submissionId/jobId; reuse with a different body returns 409.

Minimum string length: 1
​
x-request-id
string

Optional; echoed when possible. Server generates when absent.

Body

application/json

Canonical Type A ingestion JSON (canonical_submission_v1). At least one of markers or reportDocuments must be non-empty (Zod superRefine). Cross-field smoking and family-history rules are Zod-only.

​
schemaVersion
enum<string>
required
Available options:
canonical_submission_v1
​
partnerId
string<uuid>
required
​
partnerSubmissionId
string
required
Required string length: 1 - 512
​
partnerSubjectId
string
required
Required string length: 1 - 512
​
subject
object
required
​
options
object
required
​
markers
object[]
​
reportDocuments
object[]
​
questionnaire
object
​
sourceMetadata
object
​
clinicalExtensions
object

Optional partner extensions; keys scanned for disallowed direct identifiers. Rules enforced in Zod.

Response

Accepted — submission persisted; pipeline job enqueued

​
submissionId
string<uuid>
required
​
jobId
string<uuid>
required
​
partnerSubmissionId
string
required
​
partnerSubjectId
string
required
​
status
enum<string>
required

Partner-facing ingestion outcome for this endpoint. The persisted Submission.status in PostgreSQL continues to reflect pipeline state (e.g. PROCESSING).

Available options:
accepted