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

# Growers

> Create and manage grower accounts that organize farms and fields. Growers are the top-level entity grouping farm and field data for a farming operation.

Use the growers endpoints to create or manage grower records and to bulk-enable preview fields for onboarding. This page is the narrow reference for grower-specific operations, while farms and fields live in the broader fields reference.

For conceptual background, see [Growers](/fields/growers).

## Base URL

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

## Endpoints

| Endpoint                                                            | Method                                                           | Path                               |
| ------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------- |
| [Get all growers](#get-all-growers)                                 | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span>  | `/growers`                         |
| [Get a grower](#get-a-grower)                                       | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span>  | `/users/{leafUserId}/growers/{id}` |
| [Create a grower](#create-a-grower)                                 | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>POST</span> | `/users/{leafUserId}/growers`      |
| [Update a grower](#update-a-grower)                                 | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>PUT</span>  | `/users/{leafUserId}/growers/{id}` |
| [Enable preview fields by grower](#enable-preview-fields-by-grower) | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>POST</span> | `/growers/enableSync`              |

***

### Get all growers

<span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span> `/growers`

Returns a paginated list of growers available to the authenticated API owner. Use `leafUserId` to narrow the list to one Leaf user.

#### Parameters

| Parameter                | Type          | Description                                                                   |
| ------------------------ | ------------- | ----------------------------------------------------------------------------- |
| `leafUserId`             | string (UUID) | Filter by Leaf user.                                                          |
| `provider`               | string        | Filter by provider name (`JohnDeere`, `ClimateFieldView`, `CNHI`, `Trimble`). |
| `name`                   | string        | Filter by grower name.                                                        |
| `providerOrganizationId` | string        | Filter by the organization ID on the provider side.                           |
| `providerCompanyId`      | string        | Filter by the company ID on the provider side.                                |
| `providerGrowerId`       | string        | Filter by the grower ID on the provider side.                                 |
| `page`                   | integer       | Page number (default `0`).                                                    |
| `size`                   | integer       | Page size (default `20`, max `100`).                                          |
| `sort`                   | string        | Sorting order with optional `,asc` or `,desc` suffix.                         |

<Info>The default page size is 20 when `page` and `size` are not set.</Info>

#### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/fields/api/growers?leafUserId=1d3ecb0f-bf3d-42db-aae6-8c45c045d28c'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = "YOUR_TOKEN"
  endpoint = "https://api.withleaf.io/services/fields/api/growers"
  headers = {"Authorization": f"Bearer {TOKEN}"}
  params = {"leafUserId": "1d3ecb0f-bf3d-42db-aae6-8c45c045d28c"}

  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/fields/api/growers'
  const headers = { Authorization: `Bearer ${TOKEN}` }
  const params = { leafUserId: '1d3ecb0f-bf3d-42db-aae6-8c45c045d28c' }

  axios.get(endpoint, { headers, params })
    .then(res => console.log(res.data))
    .catch(console.error)
  ```
</CodeGroup>

#### Response

```json theme={null}
[
  {
    "id": 873300016,
    "name": "1Grower",
    "leafUserId": "1d3ecb0f-bf3d-42db-aae6-8c45c045d28c",
    "providerName": "JohnDeere",
    "providerId": 2,
    "providerGrowerId": "1Grower",
    "farmIds": [],
    "createdTime": "2023-06-06T03:31:39.966630Z",
    "updatedTime": "2023-06-07T20:01:14.814346Z"
  }
]
```

<Note>For John Deere, growers correspond to John Deere "Clients." The `name` property comes directly from the Client name.</Note>

***

### Get a grower

<span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span> `/users/{leafUserId}/growers/{id}`

Returns a single grower by ID.

#### Parameters

| Parameter    | Type           | Description       |
| ------------ | -------------- | ----------------- |
| `leafUserId` | path (UUID)    | The Leaf user ID. |
| `id`         | path (integer) | The grower ID.    |

#### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/fields/api/users/1d3ecb0f-bf3d-42db-aae6-8c45c045d28c/growers/873300016'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = "YOUR_TOKEN"
  endpoint = "https://api.withleaf.io/services/fields/api/users/1d3ecb0f-bf3d-42db-aae6-8c45c045d28c/growers/873300016"
  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 endpoint = 'https://api.withleaf.io/services/fields/api/users/1d3ecb0f-bf3d-42db-aae6-8c45c045d28c/growers/873300016'
  const headers = { Authorization: `Bearer ${TOKEN}` }

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

#### Response

```json theme={null}
{
  "id": 873300016,
  "name": "1Grower",
  "leafUserId": "1d3ecb0f-bf3d-42db-aae6-8c45c045d28c",
  "providerName": "JohnDeere",
  "providerId": 2,
  "providerGrowerId": "1Grower",
  "farmIds": [],
  "createdTime": "2023-06-06T03:31:39.966630Z",
  "updatedTime": "2023-06-07T20:01:14.814346Z"
}
```

***

### Create a grower

<span style={{fontWeight: 'bold', color: '#eab308'}}>POST</span> `/users/{leafUserId}/growers`

Creates a grower for the specified Leaf user. Leaf assigns an auto-generated integer ID.

#### Parameters

| Parameter    | Type        | Description       |
| ------------ | ----------- | ----------------- |
| `leafUserId` | path (UUID) | The Leaf user ID. |

#### Request body

```json theme={null}
{
  "name": "Smith Farms"
}
```

Only the `name` field is accepted.

#### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Smith Farms"}' \
    'https://api.withleaf.io/services/fields/api/users/{leafUserId}/growers'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = "YOUR_TOKEN"
  endpoint = "https://api.withleaf.io/services/fields/api/users/{leafUserId}/growers"
  headers = {"Authorization": f"Bearer {TOKEN}"}

  data = {"name": "Smith Farms"}

  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/fields/api/users/{leafUserId}/growers'
  const headers = { Authorization: `Bearer ${TOKEN}` }

  const data = { name: 'Smith Farms' }

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

#### Response

Returns the created grower object.

***

### Update a grower

<span style={{fontWeight: 'bold', color: '#eab308'}}>PUT</span> `/users/{leafUserId}/growers/{id}`

Updates the grower's `name`.

#### Parameters

| Parameter    | Type           | Description       |
| ------------ | -------------- | ----------------- |
| `leafUserId` | path (UUID)    | The Leaf user ID. |
| `id`         | path (integer) | The grower ID.    |

#### Request body

```json theme={null}
{
  "name": "Updated Grower Name"
}
```

#### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Updated Grower Name"}' \
    'https://api.withleaf.io/services/fields/api/users/{leafUserId}/growers/{id}'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = "YOUR_TOKEN"
  endpoint = "https://api.withleaf.io/services/fields/api/users/{leafUserId}/growers/{id}"
  headers = {"Authorization": f"Bearer {TOKEN}"}

  data = {"name": "Updated Grower Name"}

  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/fields/api/users/{leafUserId}/growers/{id}'
  const headers = { Authorization: `Bearer ${TOKEN}` }

  const data = { name: 'Updated Grower Name' }

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

#### Response

Returns the updated grower object.

***

### Enable preview fields by grower

<span style={{fontWeight: 'bold', color: '#eab308'}}>POST</span> `/growers/enableSync`

Enables sync for John Deere fields in `PREVIEW` status under the specified growers. Matching fields are moved to `WAITING` and queued for sync.

<Tip>Use this when the `customDataSync` configuration is enabled. This is faster than enabling fields individually when you want to onboard an entire grower.</Tip>

#### Request body

```json theme={null}
{
  "growerIds": [873300016, 873300017]
}
```

#### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"growerIds":[873300016,873300017]}' \
    'https://api.withleaf.io/services/fields/api/growers/enableSync'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = "YOUR_TOKEN"
  endpoint = "https://api.withleaf.io/services/fields/api/growers/enableSync"
  headers = {"Authorization": f"Bearer {TOKEN}"}

  data = {"growerIds": [873300016, 873300017]}

  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/fields/api/growers/enableSync'
  const headers = { Authorization: `Bearer ${TOKEN}` }

  const data = { growerIds: [873300016, 873300017] }

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

#### Response

```json theme={null}
{
  "affectedFieldIds": [
    "field-id-1",
    "field-id-2"
  ]
}
```