---
title: "Get property treatment, spray or paddock-input registers"
method: GET
path: "/farms/{farm_id}/treatment-register"
tags: ["Treatment register"]
---

# Get property treatment, spray or paddock-input registers

`GET /farms/{farm_id}/treatment-register`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/farms/{farm_id}/treatment-register`
- Auth: HTTP bearer

A register of a property as data, of one `kind`:

* `register` (the default): the LPA Section 2 treatment register, one row per PRODUCT of each
  COMPLETED treatment or husbandry record on the chosen mobs in the date range, oldest first,
  plus the same rows grouped per mob and a `summary`. A husbandry record with no product has no
  row. `expiry` and `route` are what was entered; `not recorded` where nobody did.
* `nvd`: only treatments still under a withholding period or export interval today, grouped per
  mob, for the National Vendor Declaration treatment question.
* `spray`: the chemical use register, one row per spray product on the chosen paddocks, with the
  crop, area, rate, water rate, method, applicator, the first weather reading and the grazing and
  harvest end dates, grouped per paddock.
* `paddock-inputs`: one row per product line of each fertiliser and sowing on the chosen paddocks:
  the rate, total, method or placement, analysis and who applied it. Fertiliser never holds a
  paddock back; only a seed treatment shows a grazing end date.

The preview and the compliance export's registers are drawn from the same records. A paddock register
carries `columns` (the table's headings) and `paddocks`; the others carry `mobs`. Every value a
record should carry and does not is the literal text `not recorded`, never empty (a genuinely
optional value is null). `property.pic` is null (the property has no PIC field).

Plain JSON, not JSON:API. Needs read access to the property's records: any member of the
owning business (a viewer included) or the person on a personal property, and an assistant
within its read grant. A property shared publicly or by link does NOT share its treatment
register. Not cached.

## Path parameters

- `farm_id` string, required

## Query parameters

- `scope` 'property' | 'mobs' | 'paddocks'
- `mob_ids` string[]
- `paddock_ids` string[]
- `from` string, date
- `to` string, date
- `kind` 'register' | 'nvd' | 'spray' | 'paddock-inputs'

## Response `200`

The register.

- TreatmentRegisterResponse: A register as data: the treatment register and the NVD list (about mobs), or the spray and paddock inputs registers (about paddocks). Plain JSON (not JSON:API): the same body is returned for both Accept types. The compliance export reads the same records. A register of mobs carries `mobs`; one of paddocks carries `paddocks`, `columns` (the table's headings, so any client draws it the same way) and `definitions` (the footer line).
  - `kind` 'register' | 'nvd' | 'spray' | 'paddock-inputs', required
  - `title` string, required
  - `scope` 'property' | 'mobs' | 'paddocks', required
  - `property` object, required
    - `id` string
    - `name` string
    - `pic` string, nullable: The property identification code. The property has no PIC field yet, so this is null and a file prints `not recorded`.
  - `range` object, required
    - `from` string, date
    - `to` string, date
  - `today` string, date, required
  - `columns` PaddockRegisterColumn[]: Paddock registers only. The headings of the table, in order.
    - `key` string: The key of the value in each row.
    - `label` string: The heading to print.
    - `width` integer: A relative width; scale to the space available.
  - `definitions` string: Paddock registers only. The footer line that defines the terms used.
  - `rows` union[], required
    - union
      - TreatmentRegisterRow: One PRODUCT of one completed treatment or husbandry record: a row of the LPA Section 2 treatment register. A value the record does not carry is the literal text `not recorded` (never empty), and `not_recorded` lists those keys so a client can set them in amber italic. Dates are ISO 8601 (`YYYY-MM-DD`) or `not recorded`. `expiry` and `route` are what was entered, and `not recorded` where nobody did (a husbandry record has no route).
        - `record_type` 'treatment' | 'husbandry': Whether the record is a treatment given to the mob or husbandry done to it (a product given at marking).
        - `what` string: What it was, in a farmer's words: `Drench`, `Vaccine`, `Lice`, or for husbandry the procedures, e.g. `Marking, Tail docking`.
        - `record_id` string: The drench record. Omitted on a shared link.
        - `task_id` string: The task that is the record. Omitted on a shared link.
        - `mob_id` string: Omitted on a shared link.
        - `treatment_date` string, required
        - `mob` string, required
        - `location` string, required: The paddock the mob was in on the treatment date, or `not recorded`.
        - `head` string, required: Head treated, as a string, or `not recorded`.
        - `product` string, required: Product trade name, or `not recorded`.
        - `batch` string, required
        - `expiry` string, required
        - `dose` string, required
        - `route` string, required
        - `whp_days` string, required: This product's withholding period in days, or `not recorded` (0 days is treated as not entered).
        - `esi_days` string, required
        - `safe_for_slaughter_on` string, required: Treatment date plus the longest WHP among the record's named products, or `not recorded`.
        - `export_eligible_on` string, required: Treatment date plus the longest ESI among the record's named products, or `not recorded`.
        - `treated_by` string, required
        - `under_withholding` boolean, required: Whether either safe date is still ahead of today (the whole record, not just this product).
        - `not_recorded` string[], required
      - PaddockRegisterRow: One PRODUCT line of one completed spray, fertiliser or sowing: a row of a paddock register. The keys are the register's `columns`. A value the record should carry and does not is the literal text `not recorded` (listed in `not_recorded`); a value that is genuinely optional and absent is null (print an em dash). Dates are ISO 8601 (`YYYY-MM-DD`). Spray rows carry `spray_date`, `paddock`, `crop`, `area_ha`, `product`, `batch`, `rate`, `water_rate`, `method`, `applicator`, `done_for`, `weather` and the two end dates `safe_to_graze_on` and `safe_to_harvest_on`. Paddock input rows carry `input_date`, `paddock`, `area_ha`, `operation`, `role`, `product`, `rate`, `total_kg`, `method`, `analysis`, `batch`, `applicator` and `safe_to_graze_on` (a seed treatment only).
        - `record_id` string: Omitted on a shared link.
        - `task_id` string: Omitted on a shared link.
        - `paddock_id` string: Omitted on a shared link.
        - `paddock` string
        - `under_withholding` boolean: A spray row whose grazing or harvest date is still ahead today. Always false for paddock inputs.
        - `not_recorded` string[]
  - `mobs` TreatmentRegisterMob[]: The treatment register and the NVD list only.
    - `id` string: Omitted on a shared link.
    - `name` string, required
    - `head` integer, nullable, required: The mob's head count, null until counted.
    - `status` 'under_withholding' | 'clear', required
    - `safe_for_slaughter_on` string, nullable, required: The latest safe-for-slaughter date among the treatments, or null when none is recorded.
    - `export_eligible_on` string, nullable, required
    - `treatments` TreatmentRegisterRow[], required
      - `record_type` 'treatment' | 'husbandry': Whether the record is a treatment given to the mob or husbandry done to it (a product given at marking).
      - `what` string: What it was, in a farmer's words: `Drench`, `Vaccine`, `Lice`, or for husbandry the procedures, e.g. `Marking, Tail docking`.
      - `record_id` string: The drench record. Omitted on a shared link.
      - `task_id` string: The task that is the record. Omitted on a shared link.
      - `mob_id` string: Omitted on a shared link.
      - `treatment_date` string, required
      - `mob` string, required
      - `location` string, required: The paddock the mob was in on the treatment date, or `not recorded`.
      - `head` string, required: Head treated, as a string, or `not recorded`.
      - `product` string, required: Product trade name, or `not recorded`.
      - `batch` string, required
      - `expiry` string, required
      - `dose` string, required
      - `route` string, required
      - `whp_days` string, required: This product's withholding period in days, or `not recorded` (0 days is treated as not entered).
      - `esi_days` string, required
      - `safe_for_slaughter_on` string, required: Treatment date plus the longest WHP among the record's named products, or `not recorded`.
      - `export_eligible_on` string, required: Treatment date plus the longest ESI among the record's named products, or `not recorded`.
      - `treated_by` string, required
      - `under_withholding` boolean, required: Whether either safe date is still ahead of today (the whole record, not just this product).
      - `not_recorded` string[], required
  - `paddocks` PaddockRegisterGroup[]: The spray and paddock inputs registers only.
    - `id` string: Omitted on a shared link.
    - `name` string
    - `area_ha` number, nullable
    - `status` 'clear' | 'under_withholding'
    - `safe_to_graze_on` string, date, nullable
    - `safe_to_harvest_on` string, date, nullable
    - `records` PaddockRegisterRow[]
      - `record_id` string: Omitted on a shared link.
      - `task_id` string: Omitted on a shared link.
      - `paddock_id` string: Omitted on a shared link.
      - `paddock` string
      - `under_withholding` boolean: A spray row whose grazing or harvest date is still ahead today. Always false for paddock inputs.
      - `not_recorded` string[]
  - `summary` union, required
    - TreatmentRegisterSummary: What the Export dialog's count line, amber note and empty states read.
      - `drenches` integer, required: The number of records (kept under its old name). The count line says `drench`, `treatment` or `record` by what they are.
      - `records` integer
      - `mobs` integer, required
      - `products` integer, required: Rows (one per product).
      - `line` string, required
      - `not_recorded` object, required: How many are missing, per field. A product's own fields count once per row; `head`, `location`, `treated_by` and the two safe dates once per drench. Only fields missing somewhere appear.
      - `under_withholding_mobs` integer, required
      - `empty` boolean, required
      - `empty_reason` 'no_drenches' | 'none_under_withholding' | 'null', nullable, required
    - PaddockRegisterSummary: What the Export dialog's count line, amber note and empty states read, for a paddock register.
      - `records` integer, required
      - `paddocks` integer, required
      - `products` integer, required: Rows (one per product line).
      - `line` string, required
      - `not_recorded` object, required
      - `under_withholding_paddocks` integer, required
      - `empty` boolean, required
      - `empty_reason` 'no_sprays' | 'no_inputs' | 'null', nullable, required

## Other responses

- `400`: A malformed date, an unknown kind or scope, or an end date before the start.
- `401`: Unauthenticated
- `403`: Not a member of this property's business.
- `404`: No such property.

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/06540345bbbc?raw)