Leaf User Endpoints

About

To briefly recap the Leaf User overview: a Leaf User is equivalent to the end user of your application (e.g. a grower). A Leaf User provides a way to keep your customers' data organized under your API owner. As a developer, you’ll need to create a Leaf User and connect the provider(s) you wish to integrate your platform with.

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.

Leaf Users Resources

Form of a Leaf User resource:

{
"id": "UUID",
"name": "str",
"email": "help@withleaf.io",
"phone": "str",
"address": "str",
"trimbleCredentials": {"Object"},
"cnhiCredentials": {"Object"},
"johnDeereCredentials": {"Object"},
"ravenCredentials": {"Object"},
"climateFieldViewCredentials": {"Object"},
"staraCredentials": {"Object"},
"agLeaderCredentials": {"Object"},
"ravenSlingshotCredentials": {"Object"}
}

Check the providers credentials endpoints for more details about the credentials object.

The following endpoints are available:

DescriptionEndpoints
Get all Leaf UsersGET /users/
Get a Leaf UserGET /users/{id}
Create a Leaf UserPOST /users
Update a Leaf UserPUT /users
Delete a Leaf UserDELETE /users/{id}
Get Integrations ResourcesPOST /resources

User Endpoints

Get all Leaf Users

 GET /users

Get all Leaf Users.

Request examples

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

Response

[
{
"id": "UUID",
"name": "str",
"email": "help@withleaf.io",
"phone": "str",
"address": "str",
"trimbleCredentials": {"Object"},
"cnhiCredentials": {"Object"},
"johnDeereCredentials": {"Object"},
"ravenCredentials": {"Object"},
"climateFieldViewCredentials": {"Object"},
"staraCredentials": {"Object"},
"agLeaderCredentials": {"Object"},
"ravenSlingshotCredentials": {"Object"}
},
....
]

Check the providers credentials endpoints for more details about the credentials object.

Get a Leaf User

 GET /users/{id}

Get a Leaf User by its id. This request looks up an individual Leaf User (such as a grower) and returns the details associated with their account, including provider credentials such as ID, created date and tokens.

Request examples

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

Response

{
"id": "UUID",
"name": "str",
"email": "help@withleaf.io",
"phone": "str",
"address": "str",
"trimbleCredentials": {"Object"},
"cnhiCredentials": {"Object"},
"johnDeereCredentials": {"Object"},
"ravenCredentials": {"Object"},
"climateFieldViewCredentials": {"Object"},
"staraCredentials": {"Object"},
"agLeaderCredentials": {"Object"},
"ravenSlingshotCredentials": {"Object"}
}

Create a Leaf User

 POST /users

Creates a Leaf User. You will need to create a Leaf User when linking a provider for the first time.

Request body

{
"name": "str",
"email": "help@withleaf.io",
"phone": "str",
"address": "str"
}

Besides the four properties of the example above, once you have created credentials for a provider like John Deere, you can add an entry like the following. Specifying the ID of the credentials object previously created will link it to the Leaf User being created. This will enable you to start querying farm data from the provider. Check the providers credentials endpoints for more details about the credentials object.

"johnDeereCredentials": {
"id": "UUID"
}

Request examples

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "name": "str", "email": "help@withleaf.io", "phone": "str", "address": "str"}' \
'https://api.withleaf.io/services/usermanagement/api/users'

Response

{
"id": "UUID",
"name": "str",
"email": "help@withleaf.io",
"phone": "str",
"address": "str"
}

Update a Leaf User

 PUT /users

Edits an existing Leaf User by submitting a new one.

Request body

{
"id": "UUID",
"name": "str",
"email": "help@withleaf.io",
"phone": "str",
"address": "str"
}

Note that if the existing resource has credentials and you don't include them in the body, the new Leaf User will have no credentials. Said that, for keeping the credentials or updating them, include in the JSON above an entry. Check the providers credentials endpoints for more details about the credentials object.

"johnDeereCredentials": {
"id": "UUID"
}

Request examples

curl -X PUT \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "id": "UUID", name": "str", "email": "help@withleaf.io", "phone": "str", "address": "str"}' \
'https://api.withleaf.io/services/usermanagement/api/users'

Response

{
"id": "UUID",
"name": "str",
"email": "help@withleaf.io",
"phone": "str",
"address": "str"
}

Delete a Leaf User

 DELETE /users/{id}

Deletes an existing Leaf User by id.

Request examples

curl -X DELETE \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/users/{id}'

Get Integrations Resources

 GET /resources

Gets a paged list of Integrations Resources. It is possible to filter the results by passing some query parameters.

  • provider, only matches fields from this provider (string).
  • leafUserId, only matches fields from this user (string).
  • page, an integer specifying the page being fetched.
  • size, an integer specifying the size of the page (defaults to 20).

These last two parameters are used exclusively for paging through results.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/integrations/api/resources'

Response

[
{
"provider": "JohnDeere",
"leafUserId": "UUID",
"growers": 12,
"farms": 12,
"fields": 100
},
{
"provider": "ClimateFieldView",
"leafUserId": "UUID",
"farms": 12,
"fields": 100
},
....
]
FMIS Structure Warning

Each provider has its own implementation of the FMIS structure which you can check on the table below.

FMIS Structure Table

In this table we have the following FMIS properties available for the Integrations Resources response based on the provider that's being processed.

ProviderGrowerFarmField
JohnDeere✅✅✅
ClimateFieldView❎✅✅
CNHI✅✅✅
Trimble✅✅✅
Stara❎❎✅
Raven✅✅✅
AgVance✅✅✅

Providers credentials endpoints

tip

Please don't hesitate to contact us at help@withleaf.io to schedule a demo, ask a question, request sample data, or suggest a feature!

Edit this page