Create a sample plan, step by step guide

This walks through the full Sat-MRV chain: define the area you're sampling, order and run stratification on it, generate a sample plan, and save it so your team can start collecting physical samples.

Before you start

You need one or more registered fields and their FIELD_UUIDs, and a bearer token with the Sat-MRV permissions used below. Your company also needs an active stratification subscription — every AOI endpoint checks for one regardless of your role's permission slugs.

Step 1: Create an AOI

An AOI (Area of Interest) is the container everything else attaches to.

curl -X POST https://backend.spacenus.de/api/v1.2/sat-mrv/aois/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "North Block AOI",
    "field_uuids": ["FIELD_UUID_1", "FIELD_UUID_2"]
  }'

{
  "status": "success",
  "message": "AOI created successfully.",
  "data": {
    "aoi_uuid": "AOI_UUID",
    "name": "North Block AOI",
    "is_map_requested": false
  }
}

Save aoi_uuid — every step from here on refers back to it.

Step 2: Place a stratification data order

This is the chargeable step — wallet credit is deducted here, and it's limited to once per AOI per year.

curl -X POST https://backend.spacenus.de/api/v1.2/sat-mrv/stratification/data-processing/place-order/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi_uuid": "AOI_UUID"
  }'

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "data_uuid": "DATA_UUID"
  }
}

Save data_uuid — you'll reuse it in every step below.

Step 3: Stratify the AOI into zones

curl -X POST https://backend.spacenus.de/api/v1.2/sat-mrv/stratification/stratify/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data_uuid": "DATA_UUID",
    "number_of_zones": 5
  }'

A successful response returns 200 with the stratified result. If it comes back 422 with "Map unavailable for provided parameters", the stratification pipeline couldn't produce a result for these inputs — try adjusting number_of_zones/area_size before retrying.

Step 4: Generate a sample plan from the stratified map

curl -X POST https://backend.spacenus.de/api/v1.2/sat-mrv/stratification/stratify/plan/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data_uuid": "DATA_UUID",
    "number_of_samples": 40,
    "zone_offset": 2
  }'

{
  "status": "success",
  "message": "Map processed successfully.",
  "data": {
    "map_uuid": "DATA_UUID",
    "sample_plan": {
      "map_tag": "MAP_TAG",
      "plan_tag": "PLAN_TAG",
      "samples": [
        {"latitude": 52.5013, "longitude": 13.4029, "zone_id": 1},
        {"latitude": 52.5041, "longitude": 13.4102, "zone_id": 2}
      ]
    }
  }
}

This is a draft — note the map_tag/plan_tag in the response. Not saved yet, so it won't show up in your Saved Maps history until Step 5.

Step 5: Save the sample plan

Converts the draft into a permanent record your team can act on.

curl -X POST https://backend.spacenus.de/api/v1.2/sat-mrv/stratification/stratify/plan/save/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data_uuid": "DATA_UUID",
    "map_tag": "MAP_TAG"
  }'

A 200 confirms it's saved — it now shows up under Saved Maps. You'll usually also want to save the stratification map itself (POST stratification/stratify/save/ with the same data_uuid) so the underlying zones persist alongside the plan.

What's next

Your sample plan now has real coordinates for each sample point. As your team physically collects each sample, log it against the corresponding sample point using the Samples endpoints — see the Samples reference for how to mark a point collected and attach lab results.