Skip to content

End-to-End Upload Recipe

A concrete, end-to-end sequence for preparing and submitting an ImmPort data package through the REST API. See REST API Overview for full endpoint details.

flowchart TD
    A[Authenticate - obtain API key] --> B["GET /workspaces"]
    B --> C["GET /data/upload/documentation/templates/{workspaceId}"]
    C --> D[Fill in required templates<br/>see Template Catalog + Upload Order]
    D --> E{File size?}
    E -->|Small/simple| F["POST /data/upload/type/online<br/>or /data/upload/type/offline"]
    E -->|Large, e.g. .fcs/.fastq| G[S3 presigned or multipart flow]
    F --> H["POST /data/upload/validation"]
    G --> H
    H --> I["GET /data/upload/registration/{uploadTicketNumber}/status"]
    I -->|still processing| I
    I -->|failed| J["GET .../reports/summary<br/>fix errors, resubmit"]
    I -->|passed| K["GET .../reports/database<br/>confirm what was loaded"]
    J --> D

Step-by-step

  1. Authenticate. Create a scoped API key at https://www.dev.immport.org/auth/api/keys and send it as Authorization: Bearer <api_key> on every request (see Authentication).
  2. Discover your workspace. GET /workspaces to confirm the workspaceId you'll upload into. If reusing subjects across studies, this must be the same workspace as the originating study — see Subject Sharing Across Studies.
  3. Fetch templates. GET /data/upload/documentation/templates/{workspaceId} for a pre-populated template ZIP. Cross-check against Template Catalog and Upload Order for which ones you actually need and how they must be bundled.
  4. Populate templates. Fill in the downloaded templates (or generate them programmatically) following each template's reference page and the relevant assay workflow if applicable.
  5. Upload.
    • Small package → POST /data/upload/type/online (files attached now) or /data/upload/type/offline (register now, attach files later — e.g. via Aspera).
    • Large raw files (e.g. .fcs, sequencing reads) → the S3 presigned/multipart flow (see REST API Overview). See also Examples for full curl walkthroughs of the online/offline paths.
  6. Validate. POST /data/upload/validation with the uploadTicketNumber returned from the upload step.
  7. Poll status. GET /data/upload/registration/{uploadTicketNumber}/status until it's no longer "processing".
  8. On failure: GET .../reports/summary for the error list. Cross-reference against the Validation Rule Glossary and Common Errors FAQ, fix the template(s), and resubmit from step 5.
  9. On success: GET .../reports/database to confirm exactly what was loaded (accessions assigned, etc.) before moving on to the next package.

One study per batch

The upload engine pins a single study_accession for an entire upload batch the first time it's seen (the set-and-check-study-accession process — see Validation Rule Glossary). If you need to submit data for multiple studies, send them as separate upload packages/tickets, not one combined batch.

Idempotency / retries

If a validation call fails due to a transient error, it's safe to re-poll GET .../status — but re-running POST /data/upload/validation against a package that already has rows loaded risks duplicate User Defined ID errors (see Common Errors FAQ). Prefer checking status before blindly retrying the validation call itself.