---
title: "Create family + sessions from joint VCF (atomic)"
method: POST
path: "/api/v1/families/from-joint-vcf"
tags: ["families"]
---

# Create family + sessions from joint VCF (atomic)

`POST /api/v1/families/from-joint-vcf`

## Request

- Base URL: `https://api.helena.bio` (the document declares no server; this is the origin it was published from)
- URL: `https://api.helena.bio/api/v1/families/from-joint-vcf`
- Auth: HTTP bearer

Atomically create family + N sessions from joint VCF.

Flow:
1. Parse VCF header to get actual sample names
2. Validate user-provided sample_role_mapping against actual samples
   (Case A/B/C/D per CR NB-6)
3. Call SO atomic endpoint POST /internal/families/with-sessions
4. Return family + session IDs

Atomicity guaranteed by SO transaction layer (Jules point 4).

HEL-CR-FAMILY-EPIC-1-001

## Request body

- CreateFamilyFromJointVcfRequest: POST /api/v1/families/from-joint-vcf request body.
  - `vcf_file_path` string, required
  - `family_name` string, nullable
  - `family_notes` string, nullable
  - `inheritance_hypothesis` string, nullable
  - `sample_role_mapping` JointVcfSampleMapping[], required
    - `sample_name` string, required
    - `family_role` string, required
    - `affected_status` string, nullable
    - `sex` string, nullable
    - `clinical_profile` object, nullable
  - `staging_session_id` string, uuid, nullable
  - `filtering_preset` string: Quality filtering preset. Controls which low-quality variants are removed before annotation. Options: strict (default, quality>=30/depth>=20/GQ>=30), balanced (20/15/20), permissive (10/10/10), custom.

## Response `201`

Successful Response

- FamilyFromJointVcfResponse: Response after atomic family + sessions creation from joint VCF.
  - `family` FamilyPublicResponse, required: Family representation in public API.
    - `id` string, required
    - `created_by` string, required
    - `organization_id` string, required
    - `name` string, nullable
    - `notes` string, nullable
    - `inheritance_hypothesis` string, nullable
    - `created_at` string, nullable
    - `updated_at` string, nullable
  - `session_ids` string[], required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/helena/apis/helix-insight-variant-analysis-service.md) · [All operations](https://skmtc.dev/helena/apis/helix-insight-variant-analysis-service/llms.txt) · [OpenAPI document](https://skmtc.dev/helena/apis/helix-insight-variant-analysis-service/revisions/fe51fd20cdf1?raw)