Create Submissions - Health Yourself

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"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid submission payload",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "correlationId": "corr-example-1",
    "details": {}
  }
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>",
    "correlationId": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "IDEMPOTENCY_MISMATCH",
    "message": "Idempotency-Key was already used with a different request body",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "correlationId": "corr-example-1"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

POST

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"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid submission payload",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "correlationId": "corr-example-1",
    "details": {}
  }
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>",
    "correlationId": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "IDEMPOTENCY_MISMATCH",
    "message": "Idempotency-Key was already used with a different request body",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "correlationId": "corr-example-1"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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

Field	Required	Notes
`schemaVersion`	Yes	`canonical_submission_v1`
`partnerId`	Yes	Partner credential UUID
`partnerSubmissionId`	Yes	Your unique reference (max 512 characters)
`partnerSubjectId`	Yes	De-identified subject reference
`subject`	Yes	Demographics, measurements, history, family history
`markers`	Yes	14 blood observations (`code`, `value`, `unit`)
`options`	Yes	`requestedOutputs` + `requestedOutcomes`
`sourceMetadata`	Recommended	`sourceTimestamp`, `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

Show child attributes

options

object

required

Show child attributes

markers

object[]

Show child attributes

reportDocuments

object[]

Show child attributes

questionnaire

object

Show child attributes

sourceMetadata

object

Show child attributes

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

​Request requirements

​Top-level field reference

​Health Yourself request example

​Accepted response (202)

Authorizations

Headers

Body

Response

Request requirements

Top-level field reference

Health Yourself request example

Accepted response (`202`)