Samples

A Sample is one physical soil-sampling point generated by a sample plan. This page covers listing/retrieving samples, marking one as physically collected, and attaching soil-property lab results directly on a sample. See SatMRV API for the base URL, authentication, and response envelope shared across all of SatMRV.

Endpoints

Method	Path	Purpose
GET	`stratification/sample-plan/samples/`	List samples
GET	`stratification/sample-plan/samples/{id}/`	Retrieve a single sample
PATCH	`stratification/sample-plan/samples/{id}/collect/`	Mark a sample as physically collected
PATCH	`stratification/sample-plan/samples/{id}/soil-property/`	Attach lab results directly on the sample

All paths above are relative to https://backend.spacenus.de/api/v1.2/sat-mrv/.

Permissions

Every action here also requires your company to have an active subscription — a company without one is rejected regardless of which permission slugs its role holds.

Action	Required permission
List / Retrieve	`sample.view`
Collect / Soil property	`sample.edit`

Filtering the list

GET stratification/sample-plan/samples/ supports these query parameters:

Parameter	Matching
`order`	Exact
`sample_plan`	Exact
`latitude`	Exact
`longitude`	Exact
`is_collected`	Exact

This list endpoint is always fully unpaginated, regardless of any pagination query parameter. Every sample matching your filters comes back in one response — ?page=all isn't needed (and has no effect either way) here, unlike every other SatMRV/ANA list endpoint documented in this repo. Plan your integration around potentially large single responses if a sample plan has many points.

Response fields

Field	Notes
`id`
`tracking_number`
`sample_no`	Physical label recorded when the sample is collected
`order`	The stratification/SOC order this sample belongs to
`sample_plan`	The sample plan this sample belongs to
`latitude`
`longitude`
`is_collected`	Boolean — true once `collect` has been called
`sample_point_id`
`soil_property`	Nested, read-only — populated once lab results exist for this sample, otherwise absent/empty

Marking a sample collected

PATCH stratification/sample-plan/samples/{id}/collect/

Field	Type	Required	Notes
`sample_no`	string	No	The physical label recorded at collection time

If the sample is already marked collected, this call is idempotent: it returns 200 with message "Sample Plan Already Collected", and still applies sample_no if you sent one — nothing else about the record changes.

Otherwise it marks the sample collected (recording who collected it and when), returns 200 with message "Sample Plan Collected", and fires a real-time completion event on the backend. That event is best-effort, not guaranteed — don't build a critical path solely around receiving it.

400 is returned on an invalid request body.

Attaching soil-property results directly

PATCH stratification/sample-plan/samples/{id}/soil-property/

Body is a nested soil_property object:

Field	Required	Notes
`bulk_density`	Yes
`soc`	Yes
`clay`	No	Nullable
`sand`	No	Nullable
`silt`	No	Nullable
`humus`	No	Nullable
`p2o5`	No	Nullable
`k2o`	No	Nullable
`mg`	No	Nullable
`ph_soil`	No	Nullable
`ph_h2o`	No	Nullable

This upserts: it creates a soil-property record if this sample doesn't have one yet, or updates the existing one if it does. It returns 200 with message "Soil Property Updated" either way — there's no separate "created" message for the first call. 400 is returned on an invalid request body.

This action always writes through the Sample it's called on. If you'd rather manage soil-property records as their own resource — independent of a specific sample's collect workflow — see Soil Property for the standalone CRUD endpoint instead.

Status codes

Status	Trigger
200	List, retrieve, collect (both the collected and already-collected cases), soil-property update
400	Invalid request body on `collect` or `soil-property`
403	Missing the required permission slug, or your company has no active subscription
404	Sample not found

Examples

Mark a sample collected

curl -X PATCH "https://backend.spacenus.de/api/v1.2/sat-mrv/stratification/sample-plan/samples/SAMPLE_ID/collect/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sample_no": "SN-042"
  }'

Response:

{
  "status": "success",
  "message": "Sample Plan Collected",
  "data": {
    "id": 501,
    "tracking_number": "TRK-501",
    "sample_no": "SN-042",
    "order": 88,
    "sample_plan": 12,
    "latitude": 41.9028,
    "longitude": 12.4964,
    "is_collected": true,
    "sample_point_id": 501,
    "soil_property": null
  }
}

Attach soil-property results

curl -X PATCH "https://backend.spacenus.de/api/v1.2/sat-mrv/stratification/sample-plan/samples/SAMPLE_ID/soil-property/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "soil_property": {
      "bulk_density": 1.32,
      "soc": 2.1,
      "clay": 18.5,
      "sand": 42.0,
      "silt": 39.5,
      "ph_h2o": 6.8
    }
  }'

Response:

{
  "status": "success",
  "message": "Soil Property Updated",
  "data": {
    "soil_property": {
      "bulk_density": 1.32,
      "soc": 2.1,
      "clay": 18.5,
      "sand": 42.0,
      "silt": 39.5,
      "ph_h2o": 6.8
    }
  }
}

What's next

Once a sample is collected, you may want to attach a lab report file for it — see Sample-Point Reports — or manage soil-property records as their own resource via Soil Property.