Before writing code against the Leaf API, you need to make decisions in four areas: account structure, data needs, processing rules, and sync granularity. Getting these right upfront saves significant rework later.
The four planning decisions
Account structure — how you map API owners and Leaf users to your own accounts and growers. Nearly every Leaf implementation uses one Leaf user per grower. If your use case calls for something different, talk to your Customer Success representative first.
Data needs — which Leaf data products you consume. Field boundaries? Operation summaries? Point-level GeoJSON? Satellite imagery? Weather? The answer drives which APIs you call and which configurations you enable.
Processing rules — how Leaf cleans, filters, and merges your data. Configurations like cleanupStandardGeojson, cleanupRules, operationsRemoveOutliers, and operationsMergeRange control the output. Defaults work for most cases, but if you need results that match an existing pipeline (like SMS exports), you’ll need to tune these.
Sync granularity — which data Leaf actually pulls from providers. Configurations like customDataSync, organizationDataSync, and operationsProcessingRange control the scope. This directly affects billing, since Leaf charges by spatially unique acres.
Recommended order of operations
-
Create your API owner(s). One per environment is typical (production, test, staging). Use clear naming —
leaf-test@company.com, leaf-prod@company.com — so billing and logs are easy to distinguish.
-
Set API owner-level configurations. These become the defaults for every Leaf user you create. Get them right before connecting growers, because configuration changes are not retroactive.
-
Create a single Leaf user and connect one provider account. Start with a provider account you know well, with a small number of fields. This lets you validate your configuration choices before scaling.
-
Set up alerts. At minimum, subscribe to field events, field boundary events, machine file events, and field operation events. Alerts eliminate the need to poll Leaf for updates.
-
Validate the data. Confirm that fields, machine files, and field operations are coming through as expected. Adjust configurations if needed.
-
Scale. Connect more Leaf users, either through the API directly or through Magic Links / Leaf Link widgets.
Do not connect large provider accounts during development. Each connection processes fields and files, consuming your testing acre allotment. Use customDataSync to limit which fields Leaf processes, and organizationDataSync to limit which John Deere organizations are included.
Account structure patterns
Single API owner, many Leaf users — the most common pattern. One API owner per environment, one Leaf user per grower. Simple, clean billing, per-user configuration overrides when needed.
Multiple API owners — useful for managed service providers who serve distinct client organizations. Each client gets its own API owner, isolating data, credentials, and billing. Each API owner then holds Leaf users for that client’s growers.
Leaf does not provide a separate test environment. Create distinct API owners for test and production instead.
Configuration inheritance
Configurations set at the API owner level apply to all Leaf users under that API owner by default. You can override any configuration at the Leaf user level for individual growers.
One important detail: once you set a configuration on a Leaf user, it no longer inherits from the API owner for that setting. If you later change the API owner’s configuration, the Leaf user keeps its own value.
What to read next
The use-case guides cover specific configuration recommendations:
For controlling what data Leaf syncs and processes, see Data Sync Customization.
For understanding how Leaf’s processing rules affect output, see the Configuration reference. 
