---
title: "POST samples instances_import"
method: POST
path: "/api/v1/samples/import"
---

# POST samples instances_import

`POST /api/v1/samples/import`

## Request

- Base URL: `https://app.onecodex.com`
- URL: `https://app.onecodex.com/api/v1/samples/import`
- Auth: API key in header `X-API-Key`

## Request body

- object
  - `import_type` 'url'
  - `metadata` object, nullable
    - `custom` object, nullable: Arbitrary metadata is supported as part of a custom object. custom has two constraints: (1) it must have a depth of one (i.e., no nested records); and (2) only strings, numbers, boolean, and null values are supported as values. Example: `{"lab_tech": "Linus Pauling", "amplicon_scheme": "V3-V4"}`
    - `date_collected` string, date-time, nullable: Timestamp for when the sample was collected.
    - `date_sequenced` string, date-time, nullable: Timestamp for when the sample was sequenced.
    - `description` string, nullable
    - `external_sample_id` string, nullable: An arbitrary external sample ID, e.g., an ID in a LIMS. Up to 60 characters.
    - `library_type` 'WGS' | 'Targeted/16S' | 'Other', nullable: Allowed types of SampleMetadata.library_type. Also used to populate form dropdown in the front-end
    - `location_lat` number, nullable: The latitude `(-90.0-90.0)` of the sample location. By convention, we recommend using this for the location in which the physical specimen was collected.
    - `location_lon` number, nullable: The longitude `(-180.0-180.0)` of the sample location.
    - `location_string` string, nullable
    - `name` string, nullable
    - `platform` '454 sequencing' | '454 GS FLX' | '454 GS FLX Titanium' | 'Illumina' | 'Illumina Genome Analyzer II' | 'Illumina HiSeq' | 'Illumina HiSeq 1500' | 'Illumina HiSeq 2000' | 'Illumina HiSeq 2500' | 'Illumina HiSeq 3000' | 'Illumina HiSeq 4000' | 'Illumina HiSeq X' | 'Illumina iSeq 100' | 'Illumina MiniSeq' | 'Illumina MiSeq' | 'Illumina NextSeq' | 'Illumina NextSeq 500' | 'Illumina NextSeq 550' | 'Illumina NovaSeq' | 'Illumina NovaSeq 5000' | 'Illumina NovaSeq 6000' | 'BGISEQ' | 'BGISEQ 50' | 'Element' | 'Element AVITI' | 'Ion' | 'Ion S5' | 'Ion S5 XL' | 'Ion PGM' | 'Ion Proton' | 'Ion Torrent' | 'Oxford Nanopore' | 'Oxford Nanopore GridION X5' | 'Oxford Nanopore MinION' | 'Oxford Nanopore PromethION' | 'PacBio' | 'PacBio RS II' | 'PacBio Sequel' | 'PacBio Sequel II System' | 'PacBio Revio' | 'PacBio Onso' | 'SOLiD' | 'Solexa Genome Analyzer' | 'Sanger' | 'Other', nullable: Allowed values of SampleMetadata.platform.
    - `sample_type` 'Isolate' | 'Metagenomic' | 'Other', nullable: Allowed values for SampleMetadata.sample_type. Used to populate values in the front-end dropdown
    - `starred` boolean, nullable: Whether the sample has been starred by the user within the One Codex web application.
  - `paired_uri` string, nullable
  - `project` object, nullable
    - `__DOLLAR_REF__` string, uri
  - `tags` object[]
    - `name` string, required: The tag label or name. Name must be 30 characters or fewer.
  - `uri` string, required

## Response `200`

OK

- Samples
  - `$uri` string, required
  - `created_at` string, date-time, required: Timestamp for when the object was created on the One Codex platform, encoded as a [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp.
  - `error_msg` string, nullable: An error message if the sample failed to upload, import, or validate.
  - `filename` string, nullable: The sample filename.
  - `metadata` object, required: A metadata object.
    - `__DOLLAR_REF__` string, uri
  - `owner` object, required: The owner of the sample.
    - `__DOLLAR_REF__` string, uri
  - `primary_classification` object, nullable, required: A reference to a Classification for the sample. This will typically be the [One Codex Database](https://docs.onecodex.com/en/articles/3761205-one-codex-database) or [Targeted Loci Database](https://docs.onecodex.com/en/articles/3754219-targeted-loci-database) results as appropriate. Note that samples will not have a `primary_classification` while they are still importing or being uploaded.
    - `__DOLLAR_REF__` string, uri
  - `project` union: The project the sample belongs to (optional).
    - object
      - `__DOLLAR_REF__` string, uri
    - object
      - `__DOLLAR_REF__` string, uri
  - `size` integer, nullable: The size of the uploaded file in bytes.
  - `status` 'awaiting_data' | 'importing' | 'validating' | 'failed_validation' | 'available' | 'deleted', required: Enum for user-facing data status. This is a subset of `DataStatus` for the `status` attribute in the APIs.
  - `tags` object[]: An (optionally empty) array of references to Tags describing the sample. Tags are an additional unstructured organizational tool that complement Projects and Metadata records.
    - `__DOLLAR_REF__` string, uri
  - `updated_at` string, date-time, nullable: Timestamp for when the object was last updated on the One Codex platform, encoded as a [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp.
  - `visibility` 'public' | 'shared' | 'private' | 'importing' | 'awaiting data', required: Enum for the v1 API `visibility` attribute. Note: this is legacy and only exists for backwards-compatibility in the public v1 API.

## Changes

- **2026-11-03** `3be5a5f9bf7d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/onecodex/apis/one-codex-api-v1/changes/api/v1/samples/import/post.md)

---

[API](https://skmtc.dev/onecodex/apis/one-codex-api-v1.md) - [All operations](https://skmtc.dev/onecodex/apis/one-codex-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/onecodex/apis/one-codex-api-v1/revisions/3be5a5f9bf7d?raw)