> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withleaf.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Leaf Users

> Create and manage grower accounts (Leaf users) that connect to agricultural data providers and store field, operation, and machine data through the Leaf API.

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](/leaf-users/overview).

## Base URL

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

## Endpoints

| Action                       | Method                                                             | Path          |
| ---------------------------- | ------------------------------------------------------------------ | ------------- |
| Get all Leaf users           | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span>    | `/users`      |
| Get a Leaf user              | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span>    | `/users/{id}` |
| Create a Leaf user           | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>POST</span>   | `/users`      |
| Partially update a Leaf user | <span style={{fontWeight: 'bold', color: '#eab308'}}>PATCH</span>  | `/users/{id}` |
| Update a Leaf user           | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>PUT</span>    | `/users`      |
| Delete a Leaf user           | <span style={{fontWeight: 'bold', color: '#dc2626'}}>DELETE</span> | `/users/{id}` |

## Example resource shape

```json theme={null}
{
  "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": {}
}
```

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

***

## 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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      'https://api.withleaf.io/services/usermanagement/api/users?page=0&size=10'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
[
  {
    "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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      'https://api.withleaf.io/services/usermanagement/api/users/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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:

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

### Request

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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.

<Note>
  To update provider credentials or replace the full Leaf user object, use [PUT /users](#update-a-leaf-user) instead.
</Note>

### 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

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

Returns the full Leaf user object with the updated fields.

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

### 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:

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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. |

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

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      'https://api.withleaf.io/services/usermanagement/api/users/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'
  ```

  ```python Python theme={null}
  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)
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>