Leaf Users - Leaf Documentation

A Leaf user represents an end user of your application (for example, a grower). Each Leaf user keeps provider credentials and farm data organized under your API owner account. You create a Leaf user, attach provider credentials, and Leaf begins syncing field boundaries, machine files, and field operations from those providers. For conceptual background — what a Leaf user represents, account structure patterns, and configuration inheritance — see Leaf Users overview.

Base URL

https://api.withleaf.io/services/usermanagement/api

Endpoints

Action	Method	Path
Get all Leaf users	GET	`/users`
Get a Leaf user	GET	`/users/{id}`
Create a Leaf user	POST	`/users`
Partially update a Leaf user	PATCH	`/users/{id}`
Update a Leaf user	PUT	`/users`
Delete a Leaf user	DELETE	`/users/{id}`

Example resource shape

{
  "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address": "123 Field Rd, Ames, IA 50010",
  "externalId": "grower-9381",
  "trimbleCredentials": {},
  "cnhiCredentials": {},
  "johnDeereCredentials": {},
  "ravenCredentials": {},
  "climateFieldViewCredentials": {},
  "staraCredentials": {},
  "agLeaderCredentials": {},
  "ravenSlingshotCredentials": {}
}

This is an example resource shape, not an exhaustive list of every credential object that may appear on a Leaf user.

Get all Leaf users

GET /users Returns a paginated list of Leaf users belonging to your API owner account.

Query parameters

Parameter	Type	Description
`email`	string	Filter by email address.
`name`	string	Filter by name.
`externalId`	string	Filter by your external identifier.
`page`	integer	Page number (default `0`).
`size`	integer	Page size (max `100`).
`sort`	string	Sorting order (e.g. `name,asc`).

Request

curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/usermanagement/api/users?page=0&size=10'

import requests

TOKEN = "YOUR_TOKEN"

endpoint = "https://api.withleaf.io/services/usermanagement/api/users"
headers = {"Authorization": f"Bearer {TOKEN}"}
params = {"page": 0, "size": 10}

response = requests.get(endpoint, headers=headers, params=params)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"

const endpoint = "https://api.withleaf.io/services/usermanagement/api/users"
const headers = { Authorization: `Bearer ${TOKEN}` }

axios.get(endpoint, { headers, params: { page: 0, size: 10 } })
    .then(res => console.log(res.data))
    .catch(console.error)

Response

[
  {
    "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "address": "123 Field Rd, Ames, IA 50010",
    "externalId": "grower-9381",
    "trimbleCredentials": {},
    "cnhiCredentials": {},
    "johnDeereCredentials": {},
    "ravenCredentials": {},
    "climateFieldViewCredentials": {},
    "staraCredentials": {},
    "agLeaderCredentials": {},
    "ravenSlingshotCredentials": {}
  }
]

Get a Leaf user

GET /users/{id} Returns a single Leaf user by ID, including all linked provider credentials.

Path parameters

Parameter	Type	Description
`id`	string (UUID)	The Leaf user ID.

Request

curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/usermanagement/api/users/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'

import requests

TOKEN = "YOUR_TOKEN"
LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

endpoint = f"https://api.withleaf.io/services/usermanagement/api/users/{LEAF_USER_ID}"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"
const LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

const endpoint = `https://api.withleaf.io/services/usermanagement/api/users/${LEAF_USER_ID}`
const headers = { Authorization: `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

Response

{
  "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address": "123 Field Rd, Ames, IA 50010",
  "externalId": "grower-9381",
  "trimbleCredentials": {},
  "cnhiCredentials": {},
  "johnDeereCredentials": {},
  "ravenCredentials": {},
  "climateFieldViewCredentials": {},
  "staraCredentials": {},
  "agLeaderCredentials": {},
  "ravenSlingshotCredentials": {}
}

Create a Leaf user

POST /users Creates a new Leaf user. After creation, you can attach provider credentials to start syncing data.

Request body

Field	Type	Required	Description
`name`	string	Yes	Full name.
`email`	string	Yes	Email address.
`phone`	string	No	Phone number.
`address`	string	No	Mailing address.
`externalId`	string	No	Your own identifier for the user.

You can also attach provider credentials in the same request by including the credentials ID. For example, to link John Deere credentials:

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address": "123 Field Rd, Ames, IA 50010",
  "johnDeereCredentials": {
    "id": "a1b2c3d4-5678-9abc-def0-1234567890ab"
  }
}

Request

curl -X POST \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "address": "123 Field Rd, Ames, IA 50010"
    }' \
    'https://api.withleaf.io/services/usermanagement/api/users'

import requests

TOKEN = "YOUR_TOKEN"

endpoint = "https://api.withleaf.io/services/usermanagement/api/users"
headers = {"Authorization": f"Bearer {TOKEN}"}

data = {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "address": "123 Field Rd, Ames, IA 50010"
}

response = requests.post(endpoint, headers=headers, json=data)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"

const endpoint = "https://api.withleaf.io/services/usermanagement/api/users"
const headers = { Authorization: `Bearer ${TOKEN}` }

const data = {
    name: "Jane Smith",
    email: "jane@example.com",
    phone: "+15551234567",
    address: "123 Field Rd, Ames, IA 50010"
}

axios.post(endpoint, data, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

Response

{
  "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address": "123 Field Rd, Ames, IA 50010"
}

Partially update a Leaf user

PATCH /users/{id} Updates specific profile fields on an existing Leaf user without replacing the entire object. Only the fields you include in the request body are changed; everything else — including provider credentials — is left untouched.

To update provider credentials or replace the full Leaf user object, use PUT /users instead.

Path parameters

Parameter	Type	Description
`id`	string (UUID)	The Leaf user ID.

Request body

All fields are optional. Include only the fields you want to change.

Field	Type	Description
`name`	string	Full name. Must not be blank.
`email`	string	Email address. Must not be blank.
`phone`	string	Phone number.
`address`	string	Mailing address.
`externalId`	string	Your own identifier for the user.

Request

curl -X PATCH \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "address": "456 Harvest Ln, Ames, IA 50010"
    }' \
    'https://api.withleaf.io/services/usermanagement/api/users/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'

import requests

TOKEN = "YOUR_TOKEN"
LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

endpoint = f"https://api.withleaf.io/services/usermanagement/api/users/{LEAF_USER_ID}"
headers = {"Authorization": f"Bearer {TOKEN}"}

data = {"address": "456 Harvest Ln, Ames, IA 50010"}

response = requests.patch(endpoint, headers=headers, json=data)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"
const LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

const endpoint = `https://api.withleaf.io/services/usermanagement/api/users/${LEAF_USER_ID}`
const headers = { Authorization: `Bearer ${TOKEN}` }

const data = { address: "456 Harvest Ln, Ames, IA 50010" }

axios.patch(endpoint, data, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

Response

Returns the full Leaf user object with the updated fields.

{
  "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address": "456 Harvest Ln, Ames, IA 50010",
  "externalId": "grower-9381",
  "trimbleCredentials": {},
  "cnhiCredentials": {},
  "johnDeereCredentials": {}
}

Update a Leaf user

PUT /users Replaces an existing Leaf user with the provided object. You must include the id field in the request body.

This is a full replacement. If the existing Leaf user has provider credentials and you omit them from the request body, those credentials are removed. Always include credentials you want to keep.

Request body

Field	Type	Required	Description
`id`	string (UUID)	Yes	The Leaf user ID.
`name`	string	Yes	Full name.
`email`	string	Yes	Email address.
`phone`	string	No	Phone number.
`address`	string	No	Mailing address.
`externalId`	string	No	Your own identifier for the user.

To keep or update linked credentials, include them in the body:

{
  "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address": "456 Harvest Ln, Ames, IA 50010",
  "johnDeereCredentials": {
    "id": "a1b2c3d4-5678-9abc-def0-1234567890ab"
  }
}

Request

curl -X PUT \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "address": "456 Harvest Ln, Ames, IA 50010"
    }' \
    'https://api.withleaf.io/services/usermanagement/api/users'

import requests

TOKEN = "YOUR_TOKEN"

endpoint = "https://api.withleaf.io/services/usermanagement/api/users"
headers = {"Authorization": f"Bearer {TOKEN}"}

data = {
    "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "address": "456 Harvest Ln, Ames, IA 50010"
}

response = requests.put(endpoint, headers=headers, json=data)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"

const endpoint = "https://api.withleaf.io/services/usermanagement/api/users"
const headers = { Authorization: `Bearer ${TOKEN}` }

const data = {
    id: "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
    name: "Jane Smith",
    email: "jane@example.com",
    phone: "+15551234567",
    address: "456 Harvest Ln, Ames, IA 50010"
}

axios.put(endpoint, data, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

Response

{
  "id": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address": "456 Harvest Ln, Ames, IA 50010"
}

Delete a Leaf user

DELETE /users/{id} Deletes a Leaf user by ID. Returns HTTP 204 No Content on success.

Path parameters

Parameter	Type	Description
`id`	string (UUID)	The Leaf user ID to delete.

Deleting a Leaf user removes all associated provider credentials and stops data syncing for that user. This action cannot be undone.

Request

curl -X DELETE \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/usermanagement/api/users/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'

import requests

TOKEN = "YOUR_TOKEN"
LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

endpoint = f"https://api.withleaf.io/services/usermanagement/api/users/{LEAF_USER_ID}"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.delete(endpoint, headers=headers)
print(response.status_code)

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"
const LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

const endpoint = `https://api.withleaf.io/services/usermanagement/api/users/${LEAF_USER_ID}`
const headers = { Authorization: `Bearer ${TOKEN}` }

axios.delete(endpoint, { headers })
    .then(res => console.log(res.status))
    .catch(console.error)

​Base URL

​Endpoints

​Example resource shape

​Get all Leaf users

​Query parameters

​Request

​Response

​Get a Leaf user

​Path parameters

​Request

​Response

​Create a Leaf user

​Request body

​Request

​Response

​Partially update a Leaf user

​Path parameters

​Request body

​Request

​Response

​Update a Leaf user

​Request body

​Request

​Response

​Delete a Leaf user

​Path parameters

​Request

Base URL

Endpoints

Example resource shape

Get all Leaf users

Query parameters

Request

Response

Get a Leaf user

Path parameters

Request

Response

Create a Leaf user

Request body

Request

Response

Partially update a Leaf user

Path parameters

Request body

Request

Response

Update a Leaf user

Request body

Request

Response

Delete a Leaf user

Path parameters

Request