Fields are the core spatial entity in Leaf. You can create them manually with a boundary polygon, sync them from connected providers, or both. This page covers the practical operations for working with fields.
Creating a field
To create a field manually, POST a GeoJSON MultiPolygon geometry to the fields endpoint. Leaf creates both the field and its first active boundary from the geometry you provide.
POST /services/fields/api/users/{leafUserId}/fields
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"name": "North Quarter",
"geometry": {
"type": "MultiPolygon",
"coordinates": [[[[
[-93.4880, 41.7710],
[-93.4800, 41.7710],
[-93.4800, 41.7600],
[-93.4880, 41.7600],
[-93.4880, 41.7710]
]]]]
}
}' \
'https://api.withleaf.io/services/fields/api/users/{leafUserId}/fields'
id and name on the request body. If you omit id, Leaf generates a UUID. The id cannot be changed after creation.
Updating a field
PATCH /services/fields/api/users/{leafUserId}/fields/{id}
You can update name, farmId, and geometry on manually created fields. Provider-created fields must be updated through the provider platform.
If you update the geometry, Leaf creates a new active boundary and sets the old one to inactive.
Updating the active boundary
PUT /services/fields/api/users/{leafUserId}/fields/{fieldId}/boundary
This replaces the active boundary with a new geometry. The previous active boundary is preserved as an inactive historical record.
Syncing fields from providers
When fieldsAutoSync is enabled, Leaf pulls field boundaries from all connected providers automatically. To trigger a manual sync:
POST /services/fields/api/users/{leafUserId}/fields/sync
This schedules a sync for the Leaf user. New fields from the provider appear after the sync completes. Changed boundaries on the provider side produce new boundary records in Leaf.
Preview mode
When customDataSync is enabled, newly synced fields arrive in PREVIEW status. Preview fields have metadata (name, provider info) but no boundary geometry. To fully activate a field:
POST /services/fields/api/users/{leafUserId}/fields/{id}/enableSync
The field status changes to WAITING, and its boundary is fetched in the next sync window. After processing, the status becomes PROCESSED.
You can activate all fields under a grower at once using POST /growers/enableSync with a list of grower IDs.
Finding fields by geometry
POST /services/fields/api/users/{leafUserId}/fields/intersects
Send a MultiPolygon geometry in the request body and Leaf returns all fields that overlap it. The intersectionThreshold parameter (default 0.01, range 0.01–100) controls the minimum overlap percentage required. Leaf checks both “intersection by field” and “intersection by geometry” ratios, and returns the field if either exceeds the threshold.
Deleting a field
DELETE /services/fields/api/users/{leafUserId}/fields/{fieldId}
Only manually created fields can be deleted. Provider-created fields cannot be deleted from the Leaf side.
Uploading fields to a provider
POST /services/fields/api/users/{leafUserId}/fields/{fieldId}/integration/{providerName}
You can push a Leaf field boundary to John Deere or Climate FieldView. The field must already exist in Leaf. Leaf prevents sending a field back to the provider it came from to avoid recursive syncs.
For John Deere, add the organizationId query parameter.
What to do next
