Skip to navigation
APIsStudy ResourcesStudy Samples

Create samples

Records between 1 and 100 samples against animals on the study. The request is validated as a whole; if any item is invalid, none are created.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Path parameters

studyIdstringRequiredformat: "^sdy_[a-zA-Z0-9]{10,22}$"
The unique identifier of the study.

Headers

X-Studies-Api-VersionstringOptional

Request

The samples to record.
animal_idstringRequiredformat: "^aml_[a-zA-Z0-9]{10,22}$"
The animal the sample was taken from. Must be on the study.
statusenumRequired

Whether the sample has been collected. Only collected and planned are accepted; cancelled is rejected.

Allowed values:
team_glossary_idstring or nullOptionalformat: "^tgy_[a-zA-Z0-9]{10,22}$"

The sample type, an active entry in your team’s samples glossary. Required unless sample_definition_id is supplied, and rejected with it.

sample_definition_idstring or nullOptionalformat: "^sdf_[a-zA-Z0-9]{10,22}$"

The sample definition to create the sample from. Required when status is planned.

collected_atstring or nullOptional

When the sample was collected, as a full ISO-8601 UTC date-time: either an explicit UTC instant (offset Z or +00:00) or an offset-less date-time taken as UTC. Date-only values and non-UTC offsets are rejected. Required when status is collected, rejected when it is planned, and may not be before the animal’s date of birth.

timepointstring or nullOptional

When the sample is due relative to the study schedule, as an ISO-8601 duration such as P1D or PT4H, optionally negative. Without a sample definition its magnitude must be zero or between 1 minute and 365 days.

commentsstring or nullOptional
A comment recorded against the sample.
detailslist of objects or nullOptional

The measured attributes of the sample. Each key must be one of the sample type’s configured details and appear once, value must be a non-negative number, and unit must be one configured for the key.

metadatamap from strings to any or nullOptional
Custom fields keyed by your team's active sample metadata glossary slugs. Values may not be null.

Response headers

X-RateLimit-LimitintegerOptional
The number of requests permitted in the current rate limit window.
X-RateLimit-RemainingintegerOptional

The number of requests still available in the current rate limit window. When several limits apply, this reflects the per-API-key limit, so a request can be rejected while this value is above zero.

X-RateLimit-ResetintegerOptional
The number of seconds until the current rate limit window resets.

Response

The created samples.
datalist of objects
The samples.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error