---
title: "Group paddocks into a block"
method: POST
path: "/properties/{property_id}/blocks"
tags: ["Blocks"]
---

# Group paddocks into a block

`POST /properties/{property_id}/blocks`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/properties/{property_id}/blocks`
- Auth: HTTP bearer

Names a block on the property and, with `paddock_ids`, puts those live paddocks of the property in it ("Group into a block"); each member's `block_id` becomes the block's id. A block is a label for where paddocks sit: it has no page and no records of its own, and grouping writes, moves or removes no record. A paddock carries one block, so a paddock already in another block moves to this one. Reading the property then lists it under `blocks`, with its area and outline derived from the members.

Requires edit rights on the property. `/farms/{farm_id}/blocks` is a deprecated alias for one release.

## Path parameters

- `property_id` string, uuid, required

## Request body

- BlockCreateModelAttributes: Flat attributes-adapter request body (Content-Type application/json): the fields directly under `data`. Equivalent JSON:API shape: `BlockCreateModel`.
  - `data` object, required
    - `name` string, required
    - `kind` 'outblock' | 'irrigation_farm' | 'management', required
    - `block_number` string, nullable
    - `paddock_ids` string[]

## Response `201`

The new block.

- BlockResponseAttributes: One block in attributes-adapter shape (Accept application/json).
  - `data` object: A block's fields, as the block write endpoints answer them.
    - `id` string, uuid
    - `type` string
    - `name` string
    - `kind` 'outblock' | 'irrigation_farm' | 'management'
    - `block_number` string, nullable
    - `property_id` string, uuid
    - `paddock_ids` string[]
    - `area_ha` number, nullable
    - `hull` object, nullable
      - `type` string
      - `coordinates` unknown[]
        - unknown
    - `archived_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `401`: Unauthorized — no session.
- `403`: Forbidden — the caller may not edit this property.
- `404`: No such property, or no live block with that id on it.
- `422`: A missing or duplicate name, an unknown kind, or a `paddock_ids` entry that is not a live paddock of this property. Nothing is grouped.

---

[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/a9136f78e9fb?raw)