Skip to main content
This tutorial takes you from a fresh Leaf account to viewing standardized field operation data. You’ll authenticate, create a Leaf user, connect a provider, and query the resulting field operations.

​
Before you start

  • A Leaf account with API credentials (email and password). Register here if you don’t have one.
  • At least one provider account (John Deere, Climate FieldView, CNHi, etc.) with farm data, or test data from Leaf’s sample user.
  • cURL, Python 3, or Node.js installed.

​
Step 1: Get your Leaf token

Authenticate with your Leaf credentials to get a bearer token. This token is required for all subsequent API calls. 
curl -X POST "https://api.withleaf.io/api/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-email@example.com",
    "password": "your-password"
  }'
Save the id_token from the response. You’ll pass it as a Bearer token in the Authorization header on every request.

​
Step 2: Create a Leaf user

A Leaf user represents a single data owner (typically a grower or consultant). All provider credentials and data are organized under Leaf users.
Your account includes a sample Leaf user with pre-loaded data. You can skip this step if you just want to explore the sample data. Query GET /users to find it.
curl -X POST "https://api.withleaf.io/services/usermanagement/api/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Farmer",
    "email": "jane@example.com"
  }'
Save the id from the response. This is your leafUserId.

​
Step 3: Connect a provider

The fastest way to connect a provider is with Magic Link. It generates a shareable URL that walks the grower through OAuth without any front-end code on your side. First, configure your provider application credentials using the provider setup guides. Then create a Magic Link: 
curl -X POST "https://api.withleaf.io/services/widgets/api/magic-link/users/YOUR_LEAF_USER_ID/provider" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresIn": 900
  }'
Send the returned link to the grower. They authenticate with their provider account, and Leaf stores the credentials automatically. To restrict which providers appear, add "allowedProviders": ["JohnDeere", "ClimateFieldView"] to the request body.

​
Confirm the connection worked

After the grower completes the Magic Link flow, verify that the provider now appears for the Leaf user:
cURL
curl "https://api.withleaf.io/services/integrations/api/resources?leafUserId=YOUR_LEAF_USER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"
If this worked, the response includes a summary for the connected provider. If the provider does not appear yet, wait a few minutes and try again.
For direct API credential attachment (without Magic Link), see the provider-specific tutorials: John Deere, Climate FieldView, CNHi, Trimble, AgLeader, Stara.

​
Step 4: Wait for data processing

Once a provider is connected, Leaf begins syncing machine files. The sync-to-operations pipeline works like this:
  1. Machine files are fetched from the provider and converted to Leaf’s standard canonical format (available as GeoJSON or GeoParquet).
  2. Field operations are created by merging machine files that overlap in time and field boundary.
You can set up alerts to get notified when processing completes instead of polling.

​
Step 5: Query your field operations

Once processing finishes, query the operations for your Leaf user. 
curl "https://api.withleaf.io/services/operations/api/operations?leafUserId=YOUR_LEAF_USER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"
Each operation has an operationType of planted, applied, harvested, or tillage.

​
Step 6: Get operation details

For any operation, you can fetch the summary (aggregated stats) and the standard GeoJSON (point-level data). Summary: 
curl "https://api.withleaf.io/services/operations/api/operations/OPERATION_ID/summary" \
  -H "Authorization: Bearer YOUR_TOKEN"
Standard GeoJSON: 
curl "https://api.withleaf.io/services/operations/api/operations/OPERATION_ID/standardGeojson" \
  -H "Authorization: Bearer YOUR_TOKEN"
The standard GeoJSON contains point-level data with normalized property names like yieldVolume, seedRate, appliedRate, etc. You can filter by operationType, startTime, endTime, and other parameters.

​
What you built

You now have a working pipeline that:
  • Authenticates with the Leaf API
  • Creates Leaf users to represent growers
  • Connects data providers via Magic Link
  • Retrieves standardized field operations across providers
From here, you’ll likely want to:
Last modified on March 19, 2026