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

# Provider Organizations

> Reference for provider organization list and sync-management endpoints on the Leaf user management API (John Deere and Trimble).

Use these endpoints to list provider organizations for a Leaf user and, for John Deere, to control which organizations Leaf processes. For behavior, status meanings, and `organizationDataSync`, see [Provider Organizations](/providers/organizations).

## Base URL

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

## Endpoints

### Provider organization list

Returns connected and not-connected organizations for a provider account when the provider supports that distinction.

| Action                            | Method                                                          | Path                                           |
| --------------------------------- | --------------------------------------------------------------- | ---------------------------------------------- |
| List organizations for a provider | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span> | `/users/{leafUserId}/organizations/{provider}` |

* Supported `{provider}` values include `JohnDeere` and `Trimble`.
* John Deere returns both `connectedOrganizations` and `notConnectedOrganizations`.
* Trimble does not distinguish connected vs not connected in the same way.

### Provider organization sync management

These paths control which organizations Leaf is allowed to process for a connected account.

<Note>
  Sync-management operations in this group are **John Deere only**. Use `{provider}` = `JohnDeere`.
</Note>

| Action                        | Method                                                            | Path                                                                    |
| ----------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
| List provider organizations   | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span>   | `/users/{leafUserId}/{provider}/organizations`                          |
| Get one provider organization | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span>   | `/users/{leafUserId}/{provider}/organizations/{providerOrgId}`          |
| Update organization status    | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>PATCH</span> | `/users/{leafUserId}/{provider}/organizations/{providerOrgId}/{status}` |
| Sync provider organizations   | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>POST</span>  | `/users/{leafUserId}/{provider}/organizations/sync`                     |

## Example: organization list response

```json theme={null}
{
  "connectedOrganizations": [
    {
      "id": "organization_id_1",
      "name": "Organization Name 1",
      "managementUri": "https://connections.deere.com/connections/clientKey/connections-dialog?orgId=organization_id_1"
    }
  ],
  "notConnectedOrganizations": [
    {
      "id": "organization_id_2",
      "name": "Organization Name 2",
      "managementUri": "https://connections.deere.com/connections/clientKey/connections-dialog?orgId=organization_id_2"
    }
  ]
}
```

## Example: GET organization list

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/organizations/JohnDeere'
  ```

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

  TOKEN = "YOUR_TOKEN"
  leaf_user_id = "{leafUserId}"
  endpoint = (
      f"https://api.withleaf.io/services/usermanagement/api/users/{leaf_user_id}/organizations/JohnDeere"
  )
  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 leafUserId = "{leafUserId}";

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

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

## Provider organization resource

```json theme={null}
{
  "providerOrgId": "520674381",
  "providerOrgName": "Leaf Farms",
  "status": "SELECTED",
  "managementUri": "https://connections.deere.com/connections/clientKey/connections-dialog?orgId=Leaf Farms"
}
```

| Field             | Description                                                                           |
| ----------------- | ------------------------------------------------------------------------------------- |
| `providerOrgId`   | Provider organization ID                                                              |
| `providerOrgName` | Provider organization name                                                            |
| `managementUri`   | Provider URL to review or fix the app-to-organization connection                      |
| `status`          | Whether Leaf processes data from this organization (`SELECTED`, `PREVIEW`, `BLOCKED`) |

## Organization statuses

| Status     | Meaning                                                            |
| ---------- | ------------------------------------------------------------------ |
| `SELECTED` | Leaf processes resources from this organization.                   |
| `PREVIEW`  | Visible to Leaf but downstream resources are not processed.        |
| `BLOCKED`  | The app lacks required provider-side access for this organization. |

If a John Deere `managementUri` contains `connections-dialog`, the connection is established. If it contains `select-organizations`, setup is incomplete until you fix the provider-side connection and run a sync again.

## Sync scope configuration

`organizationDataSync` on the Leaf user configuration controls whether Leaf syncs every available organization or only those you mark `SELECTED`:

* `ALL` — sync every organization the account can access.
* `SELECTED_ONLY` — sync only organizations you set to `SELECTED` via these endpoints.

See [Configuration](/configuration/overview) and [Provider Organizations](/providers/organizations) for details and billing implications.

## Verify synced resources

Confirm grower, farm, and field counts after changing organization scope:

`GET https://api.withleaf.io/services/integrations/api/resources`

See [Integrations](/api-reference/integrations).

## What to do next

* Read [Provider Organizations](/providers/organizations) for workflows and warnings.
* Use [Provider credentials](/api-reference/providers) to connect the provider account first.
* Use [Configurations](/api-reference/configurations) for `organizationDataSync` and `customDataSync`.