Provider Organizations - Leaf Documentation

Some providers expose an organization layer above growers, farms, and fields. Leaf surfaces those organizations so you can see which ones are connected. Leaf’s organization sync-management endpoints are John Deere-only.

Organization endpoint groups

Leaf exposes two related sets of organization endpoints:

1. Provider organization list

Use this endpoint to see which organizations are connected or not connected for a provider account. GET /users/{leafUserId}/organizations/{provider}

Supported providers: JohnDeere, Trimble
John Deere returns both connected and not-connected organizations.
Trimble does not distinguish between connected and not-connected organizations.

Example response:

{
  "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"
    }
  ]
}

2. Provider organization sync management

These endpoints manage the organizations Leaf is allowed to process for a connected provider account.

These sync-management endpoints are JohnDeere-only. The {provider} value for this endpoint group must be JohnDeere.

Action	Method	Path
List provider organizations	GET	`/users/{leafUserId}/{provider}/organizations`
Get one provider organization	GET	`/users/{leafUserId}/{provider}/organizations/{providerOrgId}`
Update organization status	PATCH	`/users/{leafUserId}/{provider}/organizations/{providerOrgId}/{status}`
Sync provider organizations	POST	`/users/{leafUserId}/{provider}/organizations/sync`

Provider organization resource

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

providerOrgId is the provider’s organization ID.
providerOrgName is the provider’s organization name.
managementUri is the provider-side URL for reviewing or fixing the app-to-organization connection.
status controls whether Leaf processes data from that organization.

Organization statuses

Status	Meaning
`SELECTED`	Leaf processes resources from this organization.
`PREVIEW`	Leaf keeps the organization visible but does not process its downstream resources.
`BLOCKED`	The app does not currently have the required provider-side access for this organization.

If a John Deere managementUri contains connections-dialog, the app-to-organization connection is established. If it contains select-organizations, the setup is incomplete and the organization remains unavailable for processing until you update the provider-side connection and run a sync again.

Controlling sync scope

The organizationDataSync configuration controls whether Leaf syncs every available organization or only the organizations you explicitly select:

ALL syncs every organization the account can access.
SELECTED_ONLY syncs only organizations you mark as SELECTED.

You can combine this with customDataSync to limit both organization scope and field-level processing.

John Deere accounts often have access to many organizations. If you leave organizationDataSync at ALL, Leaf may process much more data than you expect. Use SELECTED_ONLY when you need tighter control over sync scope and billing.

Verifying what synced

Use the Integrations Resources endpoint to confirm the amount of data currently available for a Leaf user: GET https://api.withleaf.io/services/integrations/api/resources Filter by provider and leafUserId to see grower, farm, and field counts per provider. This is a good way to confirm that your organization and field sync settings are producing the expected resource counts.

What to do next

Review Configuration for organizationDataSync and customDataSync.
See Organizations API Reference for endpoint paths and methods.
See Integrations API Reference for provider resource summaries.
If you are connecting John Deere accounts with many organizations, set organizationDataSync to SELECTED_ONLY before scaling the integration.

​Organization endpoint groups

​1. Provider organization list

​2. Provider organization sync management

​Provider organization resource

​Organization statuses

​Controlling sync scope

​Verifying what synced

​What to do next

Organization endpoint groups

1. Provider organization list

2. Provider organization sync management

Provider organization resource

Organization statuses

Controlling sync scope

Verifying what synced

What to do next