Skip to main content
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

ActionMethodPath
Get all Leaf usersGET/users
Get a Leaf userGET/users/{id}
Create a Leaf userPOST/users
Update a Leaf userPUT/users
Delete a Leaf userDELETE/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

ParameterTypeDescription
emailstringFilter by email address.
namestringFilter by name.
externalIdstringFilter by your external identifier.
pageintegerPage number (default 0).
sizeintegerPage size (max 100).
sortstringSorting 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'

​
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

ParameterTypeDescription
idstring (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'

​
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

FieldTypeRequiredDescription
namestringYesFull name.
emailstringYesEmail address.
phonestringNoPhone number.
addressstringNoMailing address.
externalIdstringNoYour 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'

​
Response

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

​
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

FieldTypeRequiredDescription
idstring (UUID)YesThe Leaf user ID.
namestringYesFull name.
emailstringYesEmail address.
phonestringNoPhone number.
addressstringNoMailing address.
externalIdstringNoYour 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'

​
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

ParameterTypeDescription
idstring (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'
Last modified on March 23, 2026