Skip to main content
This guide takes you from zero to retrieving processed agricultural data. You’ll create an account, get a token, create a Leaf user, and connect a data source.

​
Before you begin

You need:
  1. A Leaf account. Contact Sales or your Customer Success representative to register an account.
  2. Provider API credentials (if connecting to a provider). Complete the provider’s developer/partner agreement and obtain your client ID and secret. Leaf can help with introductions if needed.
  3. An HTTP client. cURL works, or use the Leaf Postman Collection.
Leaf does not have a separate test environment. Create distinct API owner accounts for testing and production, e.g. leaf-test@yourcompany.com and leaf-prod@yourcompany.com.

​
Step 1: Get your token

After registering, authenticate to get a JWT token. This token goes in the Authorization: Bearer <token> header of every API request. 
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"username":"your-email@example.com","password":"your-password","rememberMe":"true"}' \
  'https://api.withleaf.io/api/authenticate'
The response contains your token: 
{
  "id_token": "eyJhbGciOi..."
}
With rememberMe set to "true", the token lasts 30 days. Set it to "false" for a 24-hour token. See Authentication for full details.

​
Step 2: Create a Leaf user

A Leaf user typically represents a grower. Each Leaf user holds provider credentials, fields, and field operations. Create one with a POST request: 
curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Test Grower","email":"grower@example.com"}' \
  'https://api.withleaf.io/services/usermanagement/api/users'
Save the returned id. You’ll use it in every subsequent call for this grower.

​
Step 3: Connect data

You have two options for getting data into Leaf: Option A: Connect a provider. Attach provider credentials to the Leaf user so Leaf automatically syncs their data. Each provider has a specific credentials schema. See the provider authentication docs for details. Option B: Upload files directly. If the grower has machine files on a USB drive or local storage, you can upload them through the API or use Leaf’s Magic Link file upload widget.
During development, avoid repeatedly connecting large provider accounts. This consumes your testing acre allotment. Use the customDataSync configuration to limit which fields Leaf processes.

​
Step 4: Retrieve your data

Once Leaf processes the connected or uploaded data, you can retrieve machine files and field operations. List machine files for the Leaf user: 
curl -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/operations/api/files?leafUserId=LEAF_USER_ID'
List field operations for the Leaf user: 
curl -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/operations/api/operations?leafUserId=LEAF_USER_ID'
Field operations require field boundaries. Without boundaries, Leaf converts machine files and produces file summaries, but cannot create operations. You can sync boundaries from a provider or create them manually via the API.
If this worked, the machine files request returns a response object whose operations array contains the discovered machine files for the Leaf user. Once Leaf has both files and field boundaries, the operations request returns standardized operations for that grower.

​
Step 5: Set up alerts

Instead of polling the API, set up webhooks to get notified when new data is ready. At a minimum, subscribe to field events, field boundary events, machine file events, and field operation events. See the Alerts documentation for the full list of available events and setup instructions.

​
What you built

You now have a working Leaf integration: an authenticated API owner, a Leaf user representing a grower, a connected data source, and the ability to retrieve processed field operations. From here:
  • Core Concepts: Understand how the data pipeline works.
  • Provider Authentication: Connect to John Deere, Climate FieldView, CNHi, and other providers.
  • Machine Data: Understand how Leaf processes machine files into field operations.
  • Fields: Manage field boundaries from providers or create your own.
  • Configurations: Control how Leaf processes and syncs data.
Last modified on March 24, 2026