Provider Organizations

About

The endpoints described here are divided into two categories. The Organizations List provides tools for listing organizations that have or have not granted access to Leaf. The Organization Sync offers tools for managing organizations to be processed, which in turn impacts associated resources such as field boundaries, operations, and assets.

All HTTP methods should be prepended by this service's endpoint:

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

See below the REST resources and their endpoints available in this service.

Endpoints

DescriptionEndpoints
Get Provider OrganizationsGET /users/{leafUserId}/organizations/{provider}
Get All Provider OrganizationsGET /users/{leafUserId}/{provider}/organizations
Get a Provider OrganizationGET /users/{leafUserId}/{provider}/organizations/{provider_org_id}
Update a Provider Organization StatusPATCH /users/{leafUserId}/{provider}/organizations/{provider_org_id}

Organizations List

Get Provider Organizations

 GET /users/{leafUserId}/organizations/{provider}

Get provider connected and disconnected organizations from Leaf User.

  • provider: can be JohnDeere or Trimble.
info

At Trimble it is not possible to differentiate which organizations are connected or not.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/organizations/{provider}'

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

Organizations Sync

info
  • The provider property value can be only be JohnDeere

Resource

The properties available for a Provider Organization are.

{
"providerOrgId": "5206781",
"providerOrgName": "TB Farms",
"status": "SELECTED"
}
  • The providerOrgId property references the organization ID value from the provider. For example, if the John Deere organization ID is 12345, then the providerOrgId should be 12345.
  • The providerOrgName property references the value of the organization name from the provider.
  • The status property represents the current state of the resource. The state of the resource can be either PREVIEW, SELECTED, or BLOCKED.
    • If the status property has the value SELECTED, all available resources will be fetched from the provider and processed.
    • If the status property has the value PREVIEW, no resources beyond the organization itself will be processed.
    • If the status property has the value BLOCKED, the organization does not have the required permissions to be processed by Leaf. To troubleshoot this issue please review Step 3 of the John Deere Authentication Guide, once the setup is complete, the resource will be available with the PREVIEW status. For any additional troubleshooting options, please reach out to help@withleaf.io

Get All Provider Organizations

 GET /users/{leafUserId}/{provider}/organizations

With this endpoint users can retrieve all organizations.

You can also pass some parameters used exclusively for paging through results. They are:

  • page, an integer specifying the page being fetched (default is 0)
  • size, an integer specifying the size of the page (default is 20, max is 100)

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/{provider}/organizations'

Response

[
{
"providerOrgId": "01011000",
"providerOrgName": "Leaf Organization",
"status": "SELECTED"
},
{
"providerOrgId": "123321",
"providerOrgName": "Agriculture Organization",
"status": "PREVIEW"
}
]

Get a Provider Organization

 GET /users/{leafUserId}/{provider}/organizations

With this endpoint users can retrieve individual provider organizations.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/{provider}/organizations/{providerOrgId}'

Response

{
"providerOrgId": "123321",
"providerOrgName": "Agriculture Organization",
"status": "PREVIEW"
}

Patch a Provider Organization

 PATCH /users/{leafUserId}/{provider}/organizations

With this endpoint, users can change the status of a provider organization. You can only change the status of a provider organization between SELECTED or PREVIEW. Also, as mentioned before, provider organizations with the BLOCKED status cannot be changed.

Request examples

curl -X PATCH \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/{provider}/organizations/{providerOrgId}/{status}'

Response

{
"providerOrgId": "123321",
"providerOrgName": "Agriculture Organization",
"status": "PREVIEW"
}
Edit this page