Skip to content

Getting Started: Workspaces and Studies

Before any data can be uploaded, you need account access, a workspace, and a registered study. This page is the step-by-step walkthrough (previously split out as a separate "Data Submission Process Guide" page), with extra detail added for anyone scripting or automating the process.

1. Create an ImmPort Account

Data Submission highlighting "Create an ImmPort Account"

Register at https://www.dev.immport.org/auth/login if you don't already have an ImmPort account. All upload APIs require an authenticated (JWT) identity — see API Reference for how that identity is passed to each endpoint.

2. Access a Workspace

Data Submission highlighting "Access a Workspace"

What a workspace is

A private, access-controlled container for uploads — data stays private until it's published as a public ImmPort study. See Workspace User Management for roles/permissions, and all studies/subjects sharing data should live in the same workspace (see Subject Sharing Across Studies).

Situation Action
New member, no workspace yet Submit the Workspace Request Form
New member, team already has a workspace Have an existing team member submit the request to add you
Existing member, adding another study Reuse your existing workspace — especially if the new study shares subjects with a prior one

For a programmatic client: once credentials are available, call GET /workspaces to enumerate the workspaces you can upload to (see API Reference). There is currently no public self-service "create workspace" API — workspace provisioning goes through the Workspace Request Form / ImmPort Helpdesk, not an automatable endpoint.

3. Register a Study

Data Submission highlighting "Register a New Study"

"Registering" a study means populating the metadata that describes its basic design (arms/cohorts, protocols, etc.). There are two independent paths — covered in detail in Two Upload Paths:

  1. Study Registration Wizard (SRW) — a guided online form.
  2. Basic Study Design template — basic_study_design.txt + protocols.txt, uploaded like any other template package.

Which one should an automated client use?

If you're scripting submissions and want a single consistent code path (fill template → validate → upload → poll status) for everything — study registration included — prefer the Basic Study Design template path. The SRW is a human-oriented multi-page form; there's no indication it has its own REST API distinct from the template upload pipeline. If you only need to register bare study metadata with no subject/sample data at all, a Study File attached via the SRW may be faster to fill out by hand, but less natural to drive programmatically.

4. Complete, Validate, and Upload Data

Data Submission highlighting "Complete, Validate, and Upload Data"

Once the study is registered (via the SRW or via submission templates), additional templates are used to upload data into it. See Template Catalog for the full template list and the manual download/fill/validate/upload steps, and Upload Order for the required template sequence and same-package bundling rules.

5. Share the Study in a Data Release

Data Submission highlighting "Share Study in Data Release"

Once you're ready to share, contact the ImmPort team at mailto:ImmPort_Helpdesk@immport.org. The ImmPort team will conduct a quality check of the data, provide feedback, and discuss timing with you. ImmPort has a monthly data release schedule — see the current Data Release Schedule.

Next: Two Upload Paths → Template Catalog → Upload Order.