Samples

Search and list samples

get

Public paginated listing of published samples with server-side filters derived from query parameters. Supports ordering using declared ordering field names.

Authorizations

AuthorizationstringOptional

Token-based authentication with required prefix "Token"

Query parameters

age_maxnumber · floatOptional

Upper bound on numeric age (numeric_age_max ≤ value).

age_minnumber · floatOptional

Lower bound on numeric age (numeric_age_min ≥ value).

batch_history_idintegerOptional

Restrict to samples registered in this batch history PK (requires view permission on the batch).

bboxstringOptional

WGS84 bounding box as min_lon,min_lat,max_lon,max_lat.

check_related_resource_idintegerOptional

Annotates rows linked to this related-resource primary key (used with list UI).

collected_afterstring · date-timeOptional

Samples with sampling_start_date on or after this instant.

collected_beforestring · date-timeOptional

Samples with sampling_end_date on or before this instant.

collectorstringOptional

Substring match on individual or institution collector label.

continentstringOptional

Continent code or label (exact field match on continent).

countrystringOptional

Country ISO 3166 code(s), comma-separated (e.g. US,CA).

current_archivestringOptional

Substring match on current archive label or alt label.

depth_maxnumber · floatOptional

Samples with depth_max ≤ this value.

depth_minnumber · floatOptional

Samples with depth_min ≥ this value.

descriptionstringOptional

Case-insensitive substring match on sample_description.

elevation_maxnumber · floatOptional

Samples with elevation ≤ this value (meters).

elevation_minnumber · floatOptional

Samples with elevation ≥ this value (meters).

exclude_child_samplesstring · enumOptional

If true, only top-level samples (parent_sample empty).

Possible values:

external_sample_idstringOptional

Exact match on external_sample_id.

field_namestringOptional

Case-insensitive match on material name verbatim (material_name_verbatim).

formatstringOptional

Reserved pass-through (same allowlist as list views).

geographic_regionstringOptional

Substring match across locality, province, location fields, etc.

geologic_age_unitstringOptional

Substring match on geologic_age_verbatim or geologic_unit.

has_agestring · enumOptional

If true, only samples with non-null numeric_age_min, numeric_age_max, or geologic_age_verbatim.

Possible values:

has_geolocationstring · enumOptional

If true, only samples with a non-null geom_latlong.

Possible values:

has_imagesstring · enumOptional

If true, only samples with a related resource of type Image.

Possible values:

has_linked_resourcesstring · enumOptional

If true, samples with linked resources excluding Image.

Possible values:

has_resource_typestringOptional

Exact case-insensitive related-resource type label (e.g. publication type labels).

igsnstringOptional

Case-insensitive substring match on IGSN.

initiativestringOptional

Substring match on initiative label or normalized label linked as cruise/program.

initiative_idintegerOptional

Restrict to samples linked to this initiative PK (requires view permission on initiative).

is_draftstring · enumOptional

If true, only drafts (authenticated, owner contexts). If false, exclude drafts.

Possible values:

launch_platformstringOptional

Substring match on launch platform label or normalized label.

launch_platform_idintegerOptional

Restrict to samples using this launch platform PK (requires view permission).

materialstringOptional

Comma-separated material type IDs; expands to descendants for FK and M2M material match.

namestringOptional

Case-insensitive substring match on sample name.

object_typestringOptional

Object type label(s); matches object_type__in.

orderingstringOptional

Sort field(s). Prefix - for descending (same as DRF OrderingFilter).

pageintegerOptional

Page number when using paginated list endpoints.

page_sizeintegerOptional

Page size when using paginated list endpoints.

platformstringOptional

Substring match on platform label or normalized label.

platform_idintegerOptional

Restrict to samples using this platform PK (requires view permission).

pointstringOptional

WKT POINT (POINT(lon lat)); use with optional radius (meters, default 1000).

polygonstringOptional

WKT or GeoJSON geometry; samples with geom_latlong inside the polygon (SRID 4326 if omitted).

published_afterstring · date-timeOptional

Samples with publish_date ≥ this instant.

published_beforestring · date-timeOptional

Samples with publish_date ≤ this instant.

qstringOptional

Search substring matched against IGSN or name.

radiusnumber · floatOptional

Radius in meters around point (ignored without point).

registered_afterstring · date-timeOptional

Samples with registration_date ≥ this instant.

registered_beforestring · date-timeOptional

Samples with registration_date ≤ this instant.

related_resource_idintegerOptional

Samples linked to this related resource PK (requires view permission).

sample_group_idintegerOptional

Samples in this sample group PK (requires view permission on the group).

sampling_methodstringOptional

Case-insensitive match on linked sampling method label.

scopestringOptional

Visibility: public (published metadata), personal (your samples), shared (SESAR code grants), personal_and_shared; other values fall back to authenticated/public rules per server logic.

sesar_codestringOptional

SESAR code(s); matches sesar_code__in.

team_namestringOptional

Restrict to samples owned by this team (must be authenticated member).

Responses

200Success

application/json

countintegerRequiredExample: 123

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=4

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=2

get/api/samples/

GET /api/samples/ HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

200Success

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "sample_id": 1,
      "igsn": "text",
      "name": "text",
      "external_sample_id": "text",
      "sesar_code": "text",
      "parent_sample": "text",
      "object_type": "text",
      "publish_date": "2026-01-01T00:00:00.000Z",
      "last_update_date": "2026-01-01T00:00:00.000Z",
      "size": "text",
      "general_material_type": "text",
      "sample_material": [
        "text"
      ],
      "field_name": "text",
      "sample_description": "text",
      "purpose": "text",
      "geologic_age_verbatim": "text",
      "numeric_age_min": "text",
      "numeric_age_max": "text",
      "numeric_age_unit": "years (yr)",
      "age_description": "text",
      "geologic_age_younger": "text",
      "geologic_age_older": "text",
      "geologic_unit": "text",
      "latitude": "text",
      "longitude": "text",
      "latitude_end": "text",
      "longitude_end": "text",
      "northing": "text",
      "easting": "text",
      "zone": "text",
      "depth_min": "text",
      "depth_max": "text",
      "depth_scale": "text",
      "vertical_datum": "NAVD88",
      "elevation": "text",
      "elevation_unit": "meters",
      "location_method": "text",
      "primary_location_type": "text",
      "primary_location_name": "text",
      "location_description": "text",
      "locality": "text",
      "locality_description": "text",
      "country": "text",
      "province": "text",
      "county": "text",
      "city": "text",
      "sampling_method": "text",
      "sampling_method_detail": "text",
      "cruise_field_prgrm": "text",
      "collectors": "text",
      "platform": "text",
      "launch_platform": "text",
      "launch_label": "text",
      "sampling_start_date": "2026-01-01T00:00:00.000Z",
      "sampling_end_date": "2026-01-01T00:00:00.000Z",
      "sampling_date_precision": "year",
      "other_names": "text",
      "registration_date": "2026-01-01T00:00:00.000Z",
      "current_archive": "text",
      "original_archive": "text",
      "current_archive_contact": "text",
      "original_archive_contact": "text",
      "is_linked": false,
      "is_draft": "text",
      "is_pending_review": "text"
    }
  ]
}

Register a new sample

post

Authenticated registration. Provide sesar_code (SESAR allocation) or team (custom DOI prefix path) together with required metadata. Nested objects such as platform, launch_platform, and collectors are the primary input style; parallel *_id shortcuts exist for trusted clients and are omitted from this schema.

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Body

Sample registration payload. Prefer nested label-based objects (e.g. platform, launch_platform, collectors with individual/institution) over optional internal primary-key shortcuts, which remain accepted by the API.

igsnstring · max: 60Optional

namestring · max: 255Required

external_sample_idstring · max: 100 · nullableOptional

sesar_codestring · nullableOptional

teamstring · nullableWrite-onlyOptional

Team name for custom DOI prefix registration (no sesar_code needed).

object_typestringRequired

general_material_typestring · nullableOptional

field_namestring · max: 255 · nullableOptional

sample_descriptionstring · nullableOptional

sizestring · max: 255 · nullableOptional

size_unitstring · max: 255 · nullableOptional

purposestring · max: 500 · nullableOptional

parent_samplestring · nullableOptional

external_parent_namestring · max: 1000 · nullableOptional

external_parent_object_typestring · nullableOptional

geologic_age_verbatimstring · max: 500 · nullableOptional

numeric_age_minstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_maxstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_unitone of · nullableOptional

string · enumOptional

years (yr) - years (yr)
thousand years (Ka) - thousand years (Ka)
million years (Ma) - million years (Ma)
billion years (Ga) - billion years (Ga)
Before Present, 1950 (BP) - Before Present, 1950 (BP)
Anno Domini (AD) - Anno Domini (AD)
Common Era (CE) - Common Era (CE)
Before Common Era (BCE) - Before Common Era (BCE)

Possible values:

undefined · enumOptionalPossible values:

age_descriptionstring · max: 1000 · nullableOptional

geologic_unitstring · max: 500 · nullableOptional

latitudestring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitudestring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

latitude_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitude_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

northingstring · decimal · nullableWrite-onlyOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

eastingstring · decimal · nullableWrite-onlyOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

zonestring · max: 32 · nullableWrite-onlyOptional

depth_minstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_maxstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_scalestring · max: 255 · nullableOptional

vertical_datumone of · nullableOptional

string · enumOptional

NAVD88 - NAVD88
MSL - Mean Sea Level (MSL)

Possible values:

undefined · enumOptionalPossible values:

elevationstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_unitone of · nullableOptional

string · enumOptional

meters - Meters
kilometers - Kilometers
feet - Feet
miles - Miles

Possible values:

undefined · enumOptionalPossible values:

location_methodstring · nullableOptional

primary_location_typestring · max: 255 · nullableOptional

primary_location_namestring · max: 1000 · nullableOptional

location_descriptionstring · max: 2000 · nullableOptional

localitystring · max: 255 · nullableOptional

locality_descriptionstring · max: 2000 · nullableOptional

countrystring · nullableOptional

provincestring · max: 255 · nullableOptional

countystring · max: 255 · nullableOptional

citystring · max: 255 · nullableOptional

sampling_methodstring · nullableOptional

Sampling method label. Matched case-insensitively against existing vocabulary.

sampling_method_detailstring · max: 1000 · nullableOptional

cruise_field_prgrmstring · nullableOptional

Initiative label. Matched against owner's existing initiatives, created if new.

launch_labelstring · max: 100 · nullableOptional

sampling_start_datestring · date-time · nullableOptional

sampling_end_datestring · date-time · nullableOptional

sampling_date_precisionone of · nullableOptional

string · enumOptional

year - Year
month - Month
day - Day
hour - Hour
minute - Minute
time - Time

Possible values:

undefined · enumOptionalPossible values:

publish_datestring · date-timeOptional

registration_datestring · date-timeRead-onlyRequired

availabilityboolean · nullableOptional

storage_locationstring · max: 255 · nullableOptional

personal_collection_storage_locationstring · max: 255 · nullableWrite-onlyOptional

Personal collection / storage location (alias for storage_location).

is_draftbooleanWrite-onlyOptional

Set true to save as draft. Internal status is derived automatically.

batch_historyinteger · nullableWrite-onlyOptional

Optional batch history to add the created sample to (e.g. mint child from a batch detail page).

other_namesstring[]Write-onlyOptional

material_typesstring[]Write-onlyOptional

List of material type labels

current_archive_idinteger · nullableWrite-onlyOptional

original_archive_idinteger · nullableWrite-onlyOptional

current_archive_contactstring · max: 1000 · nullableOptional

original_archive_contactstring · max: 1000 · nullableOptional

related_resourcesinteger[]Write-onlyOptional

IDs of publications, datasets, and other related resources to link. On update, replaces non-Image links; Image links are preserved. Omit on update to leave links unchanged.

Responses

201Success

application/json

igsnstring · max: 60Optional

namestring · max: 255Required

external_sample_idstring · max: 100 · nullableOptional

sesar_codestring · nullableOptional

teamstring · nullableWrite-onlyOptional

Team name for custom DOI prefix registration (no sesar_code needed).

object_typestringRequired

general_material_typestring · nullableOptional

field_namestring · max: 255 · nullableOptional

sample_descriptionstring · nullableOptional

sizestring · max: 255 · nullableOptional

size_unitstring · max: 255 · nullableOptional

purposestring · max: 500 · nullableOptional

parent_samplestring · nullableOptional

external_parent_namestring · max: 1000 · nullableOptional

external_parent_object_typestring · nullableOptional

geologic_age_verbatimstring · max: 500 · nullableOptional

numeric_age_minstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_maxstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_unitone of · nullableOptional

string · enumOptional

years (yr) - years (yr)
thousand years (Ka) - thousand years (Ka)
million years (Ma) - million years (Ma)
billion years (Ga) - billion years (Ga)
Before Present, 1950 (BP) - Before Present, 1950 (BP)
Anno Domini (AD) - Anno Domini (AD)
Common Era (CE) - Common Era (CE)
Before Common Era (BCE) - Before Common Era (BCE)

Possible values:

undefined · enumOptionalPossible values:

age_descriptionstring · max: 1000 · nullableOptional

geologic_unitstring · max: 500 · nullableOptional

latitudestring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitudestring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

latitude_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitude_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

northingstring · decimal · nullableWrite-onlyOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

eastingstring · decimal · nullableWrite-onlyOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

zonestring · max: 32 · nullableWrite-onlyOptional

depth_minstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_maxstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_scalestring · max: 255 · nullableOptional

vertical_datumone of · nullableOptional

string · enumOptional

NAVD88 - NAVD88
MSL - Mean Sea Level (MSL)

Possible values:

undefined · enumOptionalPossible values:

elevationstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_unitone of · nullableOptional

string · enumOptional

meters - Meters
kilometers - Kilometers
feet - Feet
miles - Miles

Possible values:

undefined · enumOptionalPossible values:

location_methodstring · nullableOptional

primary_location_typestring · max: 255 · nullableOptional

primary_location_namestring · max: 1000 · nullableOptional

location_descriptionstring · max: 2000 · nullableOptional

localitystring · max: 255 · nullableOptional

locality_descriptionstring · max: 2000 · nullableOptional

countrystring · nullableOptional

provincestring · max: 255 · nullableOptional

countystring · max: 255 · nullableOptional

citystring · max: 255 · nullableOptional

sampling_methodstring · nullableOptional

Sampling method label. Matched case-insensitively against existing vocabulary.

sampling_method_detailstring · max: 1000 · nullableOptional

cruise_field_prgrmstring · nullableOptional

Initiative label. Matched against owner's existing initiatives, created if new.

launch_labelstring · max: 100 · nullableOptional

sampling_start_datestring · date-time · nullableOptional

sampling_end_datestring · date-time · nullableOptional

sampling_date_precisionone of · nullableOptional

string · enumOptional

year - Year
month - Month
day - Day
hour - Hour
minute - Minute
time - Time

Possible values:

undefined · enumOptionalPossible values:

publish_datestring · date-timeOptional

registration_datestring · date-timeRead-onlyRequired

availabilityboolean · nullableOptional

storage_locationstring · max: 255 · nullableOptional

personal_collection_storage_locationstring · max: 255 · nullableWrite-onlyOptional

Personal collection / storage location (alias for storage_location).

is_draftbooleanWrite-onlyOptional

Set true to save as draft. Internal status is derived automatically.

batch_historyinteger · nullableWrite-onlyOptional

Optional batch history to add the created sample to (e.g. mint child from a batch detail page).

other_namesstring[]Write-onlyOptional

material_typesstring[]Write-onlyOptional

List of material type labels

current_archive_idinteger · nullableWrite-onlyOptional

original_archive_idinteger · nullableWrite-onlyOptional

current_archive_contactstring · max: 1000 · nullableOptional

original_archive_contactstring · max: 1000 · nullableOptional

related_resourcesinteger[]Write-onlyOptional

IDs of publications, datasets, and other related resources to link. On update, replaces non-Image links; Image links are preserved. Omit on update to leave links unchanged.

post/api/samples/

POST /api/samples/ HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2187

{
  "igsn": "text",
  "name": "text",
  "external_sample_id": "text",
  "sesar_code": "text",
  "team": "text",
  "object_type": "text",
  "general_material_type": "text",
  "field_name": "text",
  "sample_description": "text",
  "size": "text",
  "size_unit": "text",
  "purpose": "text",
  "parent_sample": "text",
  "external_parent_name": "text",
  "external_parent_object_type": "text",
  "geologic_age_verbatim": "text",
  "numeric_age_min": "text",
  "numeric_age_max": "text",
  "numeric_age_unit": "years (yr)",
  "age_description": "text",
  "geologic_unit": "text",
  "latitude": "text",
  "longitude": "text",
  "latitude_end": "text",
  "longitude_end": "text",
  "northing": "text",
  "easting": "text",
  "zone": "text",
  "depth_min": "text",
  "depth_max": "text",
  "depth_scale": "text",
  "vertical_datum": "NAVD88",
  "elevation": "text",
  "elevation_end": "text",
  "elevation_unit": "meters",
  "location_method": "text",
  "primary_location_type": "text",
  "primary_location_name": "text",
  "location_description": "text",
  "locality": "text",
  "locality_description": "text",
  "country": "text",
  "province": "text",
  "county": "text",
  "city": "text",
  "sampling_method": "text",
  "sampling_method_detail": "text",
  "cruise_field_prgrm": "text",
  "platform": {
    "label": "text",
    "platform_type": "text",
    "description": "text"
  },
  "launch_platform": {
    "label": "text",
    "launch_type": "text"
  },
  "launch_label": "text",
  "sampling_start_date": "2026-01-01T00:00:00.000Z",
  "sampling_end_date": "2026-01-01T00:00:00.000Z",
  "sampling_date_precision": "year",
  "publish_date": "2026-01-01T00:00:00.000Z",
  "availability": true,
  "storage_location": "text",
  "personal_collection_storage_location": "text",
  "is_draft": true,
  "batch_history": 1,
  "other_names": [
    "text"
  ],
  "material_types": [
    "text"
  ],
  "collectors": [
    {
      "description": "text",
      "individual": {
        "label": "text",
        "fname": "text",
        "lname": "text",
        "individual_uri": "text"
      },
      "institution": {
        "label": "text",
        "ror": "text",
        "city": "text",
        "country": "text"
      }
    }
  ],
  "current_archive": {
    "label": "text",
    "alt_label": "text",
    "city": "text",
    "country": "text",
    "description": "text",
    "url": "text",
    "uri": "text"
  },
  "original_archive": {
    "label": "text",
    "alt_label": "text",
    "city": "text",
    "country": "text",
    "description": "text",
    "url": "text",
    "uri": "text"
  },
  "current_archive_id": 1,
  "original_archive_id": 1,
  "current_archive_contact": "text",
  "original_archive_contact": "text",
  "related_resources": [
    1
  ]
}

201Success

{
  "igsn": "text",
  "name": "text",
  "external_sample_id": "text",
  "sesar_code": "text",
  "object_type": "text",
  "general_material_type": "text",
  "field_name": "text",
  "sample_description": "text",
  "size": "text",
  "size_unit": "text",
  "purpose": "text",
  "parent_sample": "text",
  "external_parent_name": "text",
  "external_parent_object_type": "text",
  "geologic_age_verbatim": "text",
  "numeric_age_min": "text",
  "numeric_age_max": "text",
  "numeric_age_unit": "years (yr)",
  "age_description": "text",
  "geologic_unit": "text",
  "latitude": "text",
  "longitude": "text",
  "latitude_end": "text",
  "longitude_end": "text",
  "depth_min": "text",
  "depth_max": "text",
  "depth_scale": "text",
  "vertical_datum": "NAVD88",
  "elevation": "text",
  "elevation_end": "text",
  "elevation_unit": "meters",
  "location_method": "text",
  "primary_location_type": "text",
  "primary_location_name": "text",
  "location_description": "text",
  "locality": "text",
  "locality_description": "text",
  "country": "text",
  "province": "text",
  "county": "text",
  "city": "text",
  "sampling_method": "text",
  "sampling_method_detail": "text",
  "cruise_field_prgrm": "text",
  "launch_label": "text",
  "sampling_start_date": "2026-01-01T00:00:00.000Z",
  "sampling_end_date": "2026-01-01T00:00:00.000Z",
  "sampling_date_precision": "year",
  "publish_date": "2026-01-01T00:00:00.000Z",
  "registration_date": "2026-01-01T00:00:00.000Z",
  "availability": true,
  "storage_location": "text",
  "current_archive_contact": "text",
  "original_archive_contact": "text"
}

Retrieve sample for viewing or editing

get

Returns registration-aligned sample metadata. Published samples are readable without authentication; restricted samples require authentication and view permission.

Authorizations

AuthorizationstringOptional

Token-based authentication with required prefix "Token"

Path parameters

igsnstringRequired

Responses

200Success

application/json

Read-only sample metadata aligned with registration/create payload shape (labels for vocabulary FKs, IDs where the create API accepts *_id fields).

igsnstringRead-onlyRequired

namestringRead-onlyRequired

sesar_codestringRead-onlyRequired

team_idinteger · nullableRead-onlyRequired

owner_displaystringRead-onlyRequired

object_typestringRead-onlyRequired

general_material_typestringRead-onlyRequired

field_namestringRead-onlyRequired

sample_descriptionstring · nullableRead-onlyRequired

sizestring · nullableRead-onlyRequired

size_unitstring · nullableRead-onlyRequired

purposestring · nullableRead-onlyRequired

parent_samplestringRead-onlyRequired

external_parent_namestring · nullableRead-onlyRequired

external_parent_object_typestringRead-onlyRequired

geologic_age_verbatimstring · nullableRead-onlyRequired

numeric_age_minstring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_maxstring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_unitone of · nullableRead-onlyRequired

string · enumOptional

years (yr) - years (yr)
thousand years (Ka) - thousand years (Ka)
million years (Ma) - million years (Ma)
billion years (Ga) - billion years (Ga)
Before Present, 1950 (BP) - Before Present, 1950 (BP)
Anno Domini (AD) - Anno Domini (AD)
Common Era (CE) - Common Era (CE)
Before Common Era (BCE) - Before Common Era (BCE)

Possible values:

undefined · enumOptionalPossible values:

age_descriptionstring · nullableRead-onlyRequired

geologic_unitstring · nullableRead-onlyRequired

latitudestring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitudestring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

latitude_endstring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitude_endstring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

northingstringRead-onlyRequired

eastingstringRead-onlyRequired

zonestringRead-onlyRequired

depth_minstring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_maxstring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_scalestring · nullableRead-onlyRequired

vertical_datumone of · nullableRead-onlyRequired

string · enumOptional

NAVD88 - NAVD88
MSL - Mean Sea Level (MSL)

Possible values:

undefined · enumOptionalPossible values:

elevationstring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_endstring · decimal · nullableRead-onlyRequiredPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_unitone of · nullableRead-onlyRequired

string · enumOptional

meters - Meters
kilometers - Kilometers
feet - Feet
miles - Miles

Possible values:

undefined · enumOptionalPossible values:

location_methodstringRead-onlyRequired

primary_location_typestring · nullableRead-onlyRequired

primary_location_namestring · nullableRead-onlyRequired

location_descriptionstring · nullableRead-onlyRequired

localitystring · nullableRead-onlyRequired

locality_descriptionstring · nullableRead-onlyRequired

countrystringRead-onlyRequired

provincestring · nullableRead-onlyRequired

countystring · nullableRead-onlyRequired

citystring · nullableRead-onlyRequired

sampling_methodstringRead-onlyRequired

sampling_method_detailstring · nullableRead-onlyRequired

cruise_field_prgrmstringRead-onlyRequired

cruise_field_prgrm_idinteger · nullableRead-onlyRequired

platform_idinteger · nullableRead-onlyRequired

launch_platform_idinteger · nullableRead-onlyRequired

launch_labelstring · nullableRead-onlyRequired

sampling_start_datestring · date-time · nullableRead-onlyRequired

sampling_end_datestring · date-time · nullableRead-onlyRequired

sampling_date_precisionone of · nullableRead-onlyRequired

string · enumOptional

year - Year
month - Month
day - Day
hour - Hour
minute - Minute
time - Time

Possible values:

undefined · enumOptionalPossible values:

publish_datestring · date-timeRead-onlyRequired

registration_datestring · date-timeRead-onlyRequired

availabilityboolean · nullableRead-onlyRequired

storage_locationstring · nullableRead-onlyRequired

metadata_store_statusone of · nullableRead-onlyRequired

string · enumOptional

deactivated-datacite - Deactivated (DataCite)
do-not-register - Do Not Register
registered - Registered
registered-datacite - Registered (DataCite)
registered-datacite-v2 - Registered (DataCite v2)
registered-datacite-v3 - Registered (DataCite v3)
draft - Draft
pending-review - Pending Review
pending-batch-review - Pending Batch Review

Possible values:

undefined · enumOptionalPossible values:

is_draftstringRead-onlyRequired

is_pending_reviewstringRead-onlyRequired

batch_history_idstringRead-onlyRequired

other_namesstringRead-onlyRequired

material_typesstringRead-onlyRequired

collectorsstringRead-onlyRequired

current_archive_contactstring · nullableRead-onlyRequired

original_archive_contactstring · nullableRead-onlyRequired

related_resourcesstringRead-onlyRequired

can_editstringRead-onlyRequired

can_deactivatestringRead-onlyRequired

get/api/samples/{igsn}/

GET /api/samples/{igsn}/ HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

200Success

{
  "igsn": "text",
  "name": "text",
  "sesar_code": "text",
  "team_id": 1,
  "owner_display": "text",
  "object_type": "text",
  "general_material_type": "text",
  "field_name": "text",
  "sample_description": "text",
  "size": "text",
  "size_unit": "text",
  "purpose": "text",
  "parent_sample": "text",
  "external_parent_name": "text",
  "external_parent_object_type": "text",
  "geologic_age_verbatim": "text",
  "numeric_age_min": "text",
  "numeric_age_max": "text",
  "numeric_age_unit": "years (yr)",
  "age_description": "text",
  "geologic_unit": "text",
  "latitude": "text",
  "longitude": "text",
  "latitude_end": "text",
  "longitude_end": "text",
  "northing": "text",
  "easting": "text",
  "zone": "text",
  "depth_min": "text",
  "depth_max": "text",
  "depth_scale": "text",
  "vertical_datum": "NAVD88",
  "elevation": "text",
  "elevation_end": "text",
  "elevation_unit": "meters",
  "location_method": "text",
  "primary_location_type": "text",
  "primary_location_name": "text",
  "location_description": "text",
  "locality": "text",
  "locality_description": "text",
  "country": "text",
  "province": "text",
  "county": "text",
  "city": "text",
  "sampling_method": "text",
  "sampling_method_detail": "text",
  "cruise_field_prgrm": "text",
  "cruise_field_prgrm_id": 1,
  "platform": {
    "id": 1,
    "label": "text",
    "norm_label": "text",
    "description": "text",
    "platform_type_id": 1,
    "host_platform_id": 1,
    "operator": "text",
    "operator_id": 1,
    "date_commissioned": "2026-01-01",
    "user_owner": 1,
    "team_owner": 1
  },
  "platform_id": 1,
  "launch_platform": {
    "id": 1,
    "label": "text",
    "norm_label": "text",
    "description": "text",
    "host_platform_id": 1,
    "launch_type": "text",
    "launch_type_id": 1,
    "operator": "text",
    "operator_id": 1,
    "date_commissioned": "2026-01-01",
    "user_owner": 1,
    "team_owner": 1
  },
  "launch_platform_id": 1,
  "launch_label": "text",
  "sampling_start_date": "2026-01-01T00:00:00.000Z",
  "sampling_end_date": "2026-01-01T00:00:00.000Z",
  "sampling_date_precision": "year",
  "publish_date": "2026-01-01T00:00:00.000Z",
  "registration_date": "2026-01-01T00:00:00.000Z",
  "availability": true,
  "storage_location": "text",
  "metadata_store_status": "deactivated-datacite",
  "is_draft": "text",
  "is_pending_review": "text",
  "batch_history_id": "text",
  "other_names": "text",
  "material_types": "text",
  "collectors": "text",
  "current_archive": {
    "id": 1,
    "label": "text",
    "alt_label": "text",
    "description": "text",
    "country": "text",
    "country_subdivision": "text",
    "city": "text",
    "url": "text",
    "uri": "text",
    "parent_institution": {
      "id": 1,
      "institution_type": "text",
      "label": "text",
      "alt_label": "text",
      "description": "text",
      "country": "text",
      "country_subdivision": "text",
      "city": "text",
      "ror": "text",
      "parent_institutions": "text",
      "can_edit": "text",
      "created_by": 1
    }
  },
  "original_archive": {
    "id": 1,
    "label": "text",
    "alt_label": "text",
    "description": "text",
    "country": "text",
    "country_subdivision": "text",
    "city": "text",
    "url": "text",
    "uri": "text",
    "parent_institution": {
      "id": 1,
      "institution_type": "text",
      "label": "text",
      "alt_label": "text",
      "description": "text",
      "country": "text",
      "country_subdivision": "text",
      "city": "text",
      "ror": "text",
      "parent_institutions": "text",
      "can_edit": "text",
      "created_by": 1
    }
  },
  "current_archive_contact": "text",
  "original_archive_contact": "text",
  "initiative": {
    "id": 1,
    "label": "text",
    "description": "text",
    "funding": "text",
    "begin_date": "2026-01-01T00:00:00.000Z",
    "end_date": "2026-01-01T00:00:00.000Z",
    "initiative_uri": "text",
    "user_owner": 1,
    "team_owner": 1
  },
  "related_resources": "text",
  "can_edit": "text",
  "can_deactivate": "text"
}

Partially update sample metadata

patch

Omitted fields are unchanged. When provided, other_names, material_types, and collector inputs replace prior collector agents. Archive fields set or clear the current_archive / original_archive foreign keys.

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Path parameters

igsnstringRequired

Body

igsnstringRead-onlyOptional

namestring · max: 255Optional

external_sample_idstring · max: 100 · nullableOptional

sesar_codestringRead-onlyOptional

teamstringRead-onlyOptional

object_typestringOptional

general_material_typestring · nullableOptional

field_namestring · max: 255 · nullableOptional

sample_descriptionstring · nullableOptional

sizestring · max: 255 · nullableOptional

size_unitstring · max: 255 · nullableOptional

purposestring · max: 500 · nullableOptional

parent_samplestring · nullableOptional

external_parent_namestring · max: 1000 · nullableOptional

external_parent_object_typestring · nullableOptional

geologic_age_verbatimstring · max: 500 · nullableOptional

numeric_age_minstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_maxstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_unitone of · nullableOptional

string · enumOptional

years (yr) - years (yr)
thousand years (Ka) - thousand years (Ka)
million years (Ma) - million years (Ma)
billion years (Ga) - billion years (Ga)
Before Present, 1950 (BP) - Before Present, 1950 (BP)
Anno Domini (AD) - Anno Domini (AD)
Common Era (CE) - Common Era (CE)
Before Common Era (BCE) - Before Common Era (BCE)

Possible values:

undefined · enumOptionalPossible values:

age_descriptionstring · max: 1000 · nullableOptional

geologic_unitstring · max: 500 · nullableOptional

latitudestring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitudestring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

latitude_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitude_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

northingstring · decimal · nullableWrite-onlyOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

eastingstring · decimal · nullableWrite-onlyOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

zonestring · max: 32 · nullableWrite-onlyOptional

depth_minstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_maxstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_scalestring · max: 255 · nullableOptional

vertical_datumone of · nullableOptional

string · enumOptional

NAVD88 - NAVD88
MSL - Mean Sea Level (MSL)

Possible values:

undefined · enumOptionalPossible values:

elevationstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_unitone of · nullableOptional

string · enumOptional

meters - Meters
kilometers - Kilometers
feet - Feet
miles - Miles

Possible values:

undefined · enumOptionalPossible values:

location_methodstring · nullableOptional

primary_location_typestring · max: 255 · nullableOptional

primary_location_namestring · max: 1000 · nullableOptional

location_descriptionstring · max: 2000 · nullableOptional

localitystring · max: 255 · nullableOptional

locality_descriptionstring · max: 2000 · nullableOptional

countrystring · nullableOptional

provincestring · max: 255 · nullableOptional

countystring · max: 255 · nullableOptional

citystring · max: 255 · nullableOptional

sampling_methodstring · nullableOptional

Sampling method label. Matched case-insensitively against existing vocabulary.

sampling_method_detailstring · max: 1000 · nullableOptional

cruise_field_prgrmstring · nullableOptional

Initiative label. Matched against owner's existing initiatives, created if new.

launch_labelstring · max: 100 · nullableOptional

sampling_start_datestring · date-time · nullableOptional

sampling_end_datestring · date-time · nullableOptional

sampling_date_precisionone of · nullableOptional

string · enumOptional

year - Year
month - Month
day - Day
hour - Hour
minute - Minute
time - Time

Possible values:

undefined · enumOptionalPossible values:

publish_datestring · date-timeOptional

registration_datestring · date-timeRead-onlyOptional

availabilityboolean · nullableOptional

storage_locationstring · max: 255 · nullableOptional

personal_collection_storage_locationstring · max: 255 · nullableWrite-onlyOptional

Personal collection / storage location (alias for storage_location).

is_draftbooleanWrite-onlyOptional

Set true to save as draft. Internal status is derived automatically.

batch_historyinteger · nullableWrite-onlyOptional

Optional batch history to add the created sample to (e.g. mint child from a batch detail page).

other_namesstring[]Write-onlyOptional

material_typesstring[]Write-onlyOptional

List of material type labels

current_archive_idinteger · nullableWrite-onlyOptional

original_archive_idinteger · nullableWrite-onlyOptional

current_archive_contactstring · max: 1000 · nullableOptional

original_archive_contactstring · max: 1000 · nullableOptional

related_resourcesinteger[]Write-onlyOptional

IDs of publications, datasets, and other related resources to link. On update, replaces non-Image links; Image links are preserved. Omit on update to leave links unchanged.

Responses

200Success

application/json

igsnstringRead-onlyRequired

namestring · max: 255Required

external_sample_idstring · max: 100 · nullableOptional

sesar_codestringRead-onlyRequired

teamstringRead-onlyRequired

object_typestringRequired

general_material_typestring · nullableOptional

field_namestring · max: 255 · nullableOptional

sample_descriptionstring · nullableOptional

sizestring · max: 255 · nullableOptional

size_unitstring · max: 255 · nullableOptional

purposestring · max: 500 · nullableOptional

parent_samplestring · nullableOptional

external_parent_namestring · max: 1000 · nullableOptional

external_parent_object_typestring · nullableOptional

geologic_age_verbatimstring · max: 500 · nullableOptional

numeric_age_minstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_maxstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

numeric_age_unitone of · nullableOptional

string · enumOptional

years (yr) - years (yr)
thousand years (Ka) - thousand years (Ka)
million years (Ma) - million years (Ma)
billion years (Ga) - billion years (Ga)
Before Present, 1950 (BP) - Before Present, 1950 (BP)
Anno Domini (AD) - Anno Domini (AD)
Common Era (CE) - Common Era (CE)
Before Common Era (BCE) - Before Common Era (BCE)

Possible values:

undefined · enumOptionalPossible values:

age_descriptionstring · max: 1000 · nullableOptional

geologic_unitstring · max: 500 · nullableOptional

latitudestring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitudestring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

latitude_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

longitude_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

northingstring · decimal · nullableWrite-onlyOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

eastingstring · decimal · nullableWrite-onlyOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

zonestring · max: 32 · nullableWrite-onlyOptional

depth_minstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_maxstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

depth_scalestring · max: 255 · nullableOptional

vertical_datumone of · nullableOptional

string · enumOptional

NAVD88 - NAVD88
MSL - Mean Sea Level (MSL)

Possible values:

undefined · enumOptionalPossible values:

elevationstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_endstring · decimal · nullableOptionalPattern: ^-?\d{0,10}(?:\.\d{0,20})?$

elevation_unitone of · nullableOptional

string · enumOptional

meters - Meters
kilometers - Kilometers
feet - Feet
miles - Miles

Possible values:

undefined · enumOptionalPossible values:

location_methodstring · nullableOptional

primary_location_typestring · max: 255 · nullableOptional

primary_location_namestring · max: 1000 · nullableOptional

location_descriptionstring · max: 2000 · nullableOptional

localitystring · max: 255 · nullableOptional

locality_descriptionstring · max: 2000 · nullableOptional

countrystring · nullableOptional

provincestring · max: 255 · nullableOptional

countystring · max: 255 · nullableOptional

citystring · max: 255 · nullableOptional

sampling_methodstring · nullableOptional

Sampling method label. Matched case-insensitively against existing vocabulary.

sampling_method_detailstring · max: 1000 · nullableOptional

cruise_field_prgrmstring · nullableOptional

Initiative label. Matched against owner's existing initiatives, created if new.

launch_labelstring · max: 100 · nullableOptional

sampling_start_datestring · date-time · nullableOptional

sampling_end_datestring · date-time · nullableOptional

sampling_date_precisionone of · nullableOptional

string · enumOptional

year - Year
month - Month
day - Day
hour - Hour
minute - Minute
time - Time

Possible values:

undefined · enumOptionalPossible values:

publish_datestring · date-timeOptional

registration_datestring · date-timeRead-onlyRequired

availabilityboolean · nullableOptional

storage_locationstring · max: 255 · nullableOptional

personal_collection_storage_locationstring · max: 255 · nullableWrite-onlyOptional

Personal collection / storage location (alias for storage_location).

is_draftbooleanWrite-onlyOptional

Set true to save as draft. Internal status is derived automatically.

batch_historyinteger · nullableWrite-onlyOptional

Optional batch history to add the created sample to (e.g. mint child from a batch detail page).

other_namesstring[]Write-onlyOptional

material_typesstring[]Write-onlyOptional

List of material type labels

current_archive_idinteger · nullableWrite-onlyOptional

original_archive_idinteger · nullableWrite-onlyOptional

current_archive_contactstring · max: 1000 · nullableOptional

original_archive_contactstring · max: 1000 · nullableOptional

related_resourcesinteger[]Write-onlyOptional

IDs of publications, datasets, and other related resources to link. On update, replaces non-Image links; Image links are preserved. Omit on update to leave links unchanged.

patch/api/samples/{igsn}/

PATCH /api/samples/{igsn}/ HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2139

{
  "name": "text",
  "external_sample_id": "text",
  "object_type": "text",
  "general_material_type": "text",
  "field_name": "text",
  "sample_description": "text",
  "size": "text",
  "size_unit": "text",
  "purpose": "text",
  "parent_sample": "text",
  "external_parent_name": "text",
  "external_parent_object_type": "text",
  "geologic_age_verbatim": "text",
  "numeric_age_min": "text",
  "numeric_age_max": "text",
  "numeric_age_unit": "years (yr)",
  "age_description": "text",
  "geologic_unit": "text",
  "latitude": "text",
  "longitude": "text",
  "latitude_end": "text",
  "longitude_end": "text",
  "northing": "text",
  "easting": "text",
  "zone": "text",
  "depth_min": "text",
  "depth_max": "text",
  "depth_scale": "text",
  "vertical_datum": "NAVD88",
  "elevation": "text",
  "elevation_end": "text",
  "elevation_unit": "meters",
  "location_method": "text",
  "primary_location_type": "text",
  "primary_location_name": "text",
  "location_description": "text",
  "locality": "text",
  "locality_description": "text",
  "country": "text",
  "province": "text",
  "county": "text",
  "city": "text",
  "sampling_method": "text",
  "sampling_method_detail": "text",
  "cruise_field_prgrm": "text",
  "platform": {
    "label": "text",
    "platform_type": "text",
    "description": "text"
  },
  "launch_platform": {
    "label": "text",
    "launch_type": "text"
  },
  "launch_label": "text",
  "sampling_start_date": "2026-01-01T00:00:00.000Z",
  "sampling_end_date": "2026-01-01T00:00:00.000Z",
  "sampling_date_precision": "year",
  "publish_date": "2026-01-01T00:00:00.000Z",
  "availability": true,
  "storage_location": "text",
  "personal_collection_storage_location": "text",
  "is_draft": true,
  "batch_history": 1,
  "other_names": [
    "text"
  ],
  "material_types": [
    "text"
  ],
  "collectors": [
    {
      "description": "text",
      "individual": {
        "label": "text",
        "fname": "text",
        "lname": "text",
        "individual_uri": "text"
      },
      "institution": {
        "label": "text",
        "ror": "text",
        "city": "text",
        "country": "text"
      }
    }
  ],
  "current_archive": {
    "label": "text",
    "alt_label": "text",
    "city": "text",
    "country": "text",
    "description": "text",
    "url": "text",
    "uri": "text"
  },
  "original_archive": {
    "label": "text",
    "alt_label": "text",
    "city": "text",
    "country": "text",
    "description": "text",
    "url": "text",
    "uri": "text"
  },
  "current_archive_id": 1,
  "original_archive_id": 1,
  "current_archive_contact": "text",
  "original_archive_contact": "text",
  "related_resources": [
    1
  ]
}

200Success

{
  "igsn": "text",
  "name": "text",
  "external_sample_id": "text",
  "sesar_code": "text",
  "team": "text",
  "object_type": "text",
  "general_material_type": "text",
  "field_name": "text",
  "sample_description": "text",
  "size": "text",
  "size_unit": "text",
  "purpose": "text",
  "parent_sample": "text",
  "external_parent_name": "text",
  "external_parent_object_type": "text",
  "geologic_age_verbatim": "text",
  "numeric_age_min": "text",
  "numeric_age_max": "text",
  "numeric_age_unit": "years (yr)",
  "age_description": "text",
  "geologic_unit": "text",
  "latitude": "text",
  "longitude": "text",
  "latitude_end": "text",
  "longitude_end": "text",
  "depth_min": "text",
  "depth_max": "text",
  "depth_scale": "text",
  "vertical_datum": "NAVD88",
  "elevation": "text",
  "elevation_end": "text",
  "elevation_unit": "meters",
  "location_method": "text",
  "primary_location_type": "text",
  "primary_location_name": "text",
  "location_description": "text",
  "locality": "text",
  "locality_description": "text",
  "country": "text",
  "province": "text",
  "county": "text",
  "city": "text",
  "sampling_method": "text",
  "sampling_method_detail": "text",
  "cruise_field_prgrm": "text",
  "launch_label": "text",
  "sampling_start_date": "2026-01-01T00:00:00.000Z",
  "sampling_end_date": "2026-01-01T00:00:00.000Z",
  "sampling_date_precision": "year",
  "publish_date": "2026-01-01T00:00:00.000Z",
  "registration_date": "2026-01-01T00:00:00.000Z",
  "availability": true,
  "storage_location": "text",
  "current_archive_contact": "text",
  "original_archive_contact": "text"
}

PreviousSample Groups

NextSESAR Codes

Last updated 1 month ago

Was this helpful?