KisanHub logo
API docs by Redocly

KisanHub API (1.0)

Download OpenAPI specification:Download

API Support: support@kisanhub.com

Introduction

Welcome to the KisanHub developer space! You'll find comprehensive guides and documentation to help you start working with KisanHub as quickly as possible, as well as support if you get stuck.

KisanHub is a supply management platform that brings complex agricultural and procurement data together in one convenient platform so you can better predict supply and make the most of demand.

If you have any questions, please get in touch with our team support@kisanhub.com

Authentication

KisanHub uses Bearer Authentication (also called token authentication). You must include an Authorization header when making requests to the API:

Authorization: Token <token>

Please contact support@kisanhub.com to obtain your API token. All API calls should end with a trailing /: you'll get 301 error codes if you forget this.

Units

All date-times are UTC and in RFC3339 format, although most APIs also accept simple dates without the time component (in YYYY-MM-DD format).

We use metric units throughout e.g we use hectares for area.

Language

Some APIs will return localised names where available, in response to the ACCEPT_LANGUAGE header. Note that we only use the first (language) part of the header value: e.g en-US will be converted to en. The language may also be overridden via the language query parameter for convenience. Note that at the moment the only available languages are:

  • en (English)
  • hi (Hindi)
  • mr (Marathi)

Common filters

GET APIs will be default return all information associated with the requested entity. You can retrict the fields returned by using the only query parameter. For example:

https://api.kisanhub.com/api/field/?only=id,farm_id

Glossary

The Agritech industry as a whole uses a lot of terms in often conflicting and ambiguous ways. At KisanHub we've tried to come up with a standardised set of terms that we use throughout our platform, which should mostly map onto the terms you're expecting.

Term Our meaning
User A user of the KisanHub platform.
Team A grouping of users, often mapped to an organisation
Organisation An organisation is a named legal entity. There is a 1-1 mapping between organisation and team
Site A deprecated grouped of teams. Generally the site was associated a single KisanHub enterprise customer
Farm A hub from which a collection of fields are managed. A team can have one or many farms, and controls access to the fields and related data
Field A geographical region of land owned by a Farm that can be used to grow crops.
Plot A subsection of a Field which is to be (or has already been) planted with a single crop.
Observation An observation on a plot e.g ground cover. Observation is also called 'Crop Monitoring'
Product A product that can be applied to a plot e.g pesticide, fertiliser
Genus The genus of the planted crop e.g "Potato". Note that historically this was known as a Crop, and is still referred to as such in some older APIs (e.g crop_id)
Variety The variety of the planted crop e.g "Adora"
PestDisease A general term and encompasses all pests and diseases that can afflict a crop
Primary Growth Stage A broad stage in the lifecycle of a crop, for example germination.
Secondary Growth Stage Represents a more granular metric of where a given crop is in it's Primary Growth Stage development.
Store A physical building owned by an organisation that can be used to store crop.
Store Lot StoreLot is the fraction of the store that contains, or will contain, an amount from the crop.
Customer The customer is the organisation who is paying for the produce in a transaction
Load A load is a transaction with a supplier/seller, a customer/buyer, and a crop
Trade Record A record of a load transaction that is sent to the customer and verified at intake
Trading Agreement A sales or purchase contract between two organisations
Load Ticket Another (deprecated) name for trade record
Off-platform An "off-platform" field or plot is one that is recorded on the platform but is not actively managed by us. Off-platform fields and plots have no polygons and so do not appear on the geojson APIs, but can otherwise be used as normal
Operation An operation on a plot e.g planting, harvest. An operation may either be planned or applied
Operation schedule A schedule of planned operations that can be created automatically after a specified trigger

Permissions

The following permission levels determine the actions and data that is available to the user:

Permission Description
REGISTRATION_ADMIN Registration admins can access and edit teams/users/farms and fields under their Site
CROP_QUALITY_ADMIN Allows creation and edit of crop quality templates
SITE_ADMIN DEPRECATED. Site admins can access and edit teams/users/farms/fields/plots under their Site

PUT operations

When an API accepts a PUT request the object is not replaced it is updated. Only the attributes present in the request will be altered: default values will not be set for attributes that are absent from the request. As such you should pass in the entire object in the payload unless you want the PUT to behave like a PATCH.

User

User management

List users

Returns details for all visible users. In practise this will return the details for all users in all visible teams, so the same visibility rules for teams apply here. To recap: all users will be able to see their own teammates plus the details of all users in teams which have shared one or more plots with their team.

Users with SITE_ADMIN or REGISTRATION_ADMIN permission will in additional see users for all teams associated with their Site.

Kisanhub staff members can see all users regardless.

  • All user
  • Kisanhub staff can see all users
  • Users with either the SITE_ADMIN or will be able to view all users associated with their Site
  • A user can always view users from their team connected teams with can_manage flag
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

email
string

Only return users with this email address

phone
string

Only return users with this phone number

search
string

Text search - checks first_name, last_name, email and phone_number

user_type
string
Enum: "grower" "agronomist"

Filter on the user type

include_collaborators
boolean
Deprecated
Default: false

This used to force the inclusion of users from teams which have shared plots. However that is now the default behaviour, so this has no effect and is ignored.

permission
string
Enum: "staff" "crop_quality_admin" "registration_admin"

Filter users with the specified permission

sort_field
string
Enum: "id" "name" "last_access"

Determine the sort field of returned users. Note that name sorts by first_name then last_name

sort_direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

state
string
Default: "active"
Enum: "active" "inactive"

Filter by active or inactive user state. We will default to only returning active users

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create user

Create a new user. A user with TEAM_ADMIN may create users for their own team. An Enterprise user with SITE_ADMIN permission may create users for any of their client teams. A Kisanhub staff user may create users for any teams.

Request Body schema: application/json
username
required
string

Globally unique username. This should be the either the supplied phone number or the email address

first_name
required
string

First (and middle) name

last_name
required
string

Last name

email
string

Email

is_active
boolean

Is this an active user?

team_id
integer

Primary team key

organisation_id
integer

Organisation ID

object (ContactDetails)

Contact details

object (UserDemographics)

Demographical user information

object (GrowerDetails)
Address (object) or LegacyAddress (object) (schemas-Address)

User address. Please use the newer Address schema

object (Permissions)
last_access
string <date-time>

Date-time when this user last accessed the KisanHub platform via an API call

password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Get user

Return a single user. A user with TEAM_ADMIN permission may access any users within their team. An Enterprise user with SITE_ADMIN permission view users in any of their client teams. A Kisanhub staff user may view any user.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Update user

Update an existing user. A user should always be able to update their own details. A user with TEAM_ADMIN permission may update any user within their own team. An Enterprise user with SITE_ADMIN permission may update any user in any of their client teams. A Kisanhub staff user may update any user in any team.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Request Body schema: application/json
username
required
string

Globally unique username. This should be the either the supplied phone number or the email address

first_name
required
string

First (and middle) name

last_name
required
string

Last name

email
string

Email

is_active
boolean

Is this an active user?

team_id
integer

Primary team key

organisation_id
integer

Organisation ID

object (ContactDetails)

Contact details

object (UserDemographics)

Demographical user information

object (GrowerDetails)
Address (object) or LegacyAddress (object) (schemas-Address)

User address. Please use the newer Address schema

object (Permissions)
last_access
string <date-time>

Date-time when this user last accessed the KisanHub platform via an API call

Responses

Request samples

Content type
application/json
{
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Partial user update

Partially update an existing user

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Request Body schema: application/json
username
required
string

Globally unique username. This should be the either the supplied phone number or the email address

first_name
required
string

First (and middle) name

last_name
required
string

Last name

email
string

Email

is_active
boolean

Is this an active user?

team_id
integer

Primary team key

organisation_id
integer

Organisation ID

object (ContactDetails)

Contact details

object (UserDemographics)

Demographical user information

object (GrowerDetails)
Address (object) or LegacyAddress (object) (schemas-Address)

User address. Please use the newer Address schema

object (Permissions)
last_access
string <date-time>

Date-time when this user last accessed the KisanHub platform via an API call

Responses

Request samples

Content type
application/json
{
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Reactivate user

Reactivate a user. A non-staff user may only reactivate users in their own team or in teams that they manage

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Deactivate user

Deactivate the user. A non-staff user may only deactivate users in their own team or in teams that they manage. You cannot deactivate your own user.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Validate new user

Checks whether the specified password or phone number is valid for a new user

query Parameters
phone
string

Phone number to be checked

email
string

email to be checked

Responses

Response samples

Content type
application/json
{
  • "email": "string",
  • "phone": "string"
}

Invite users

Invite one or more users by email to an organisation.

While any user may invite a user to their own organisation, permission to invite to another organisation is restricted by the following rules:

  • KisanHub staff may invite to any organisation
  • Users with registration_admin access may invite users to organisations that they are managing

Only KisanHub staff may set the is_staff or registration_admin permission, and only registration admins may set the crop_quality_admin flag.

Request Body schema: application/json
organisation_id
integer

Organisation ID. If not specified then assume the user's own organisation.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "organisation_id": 7,
  • "users": [
    ]
}

Verify invite token

Verify a user invite token and return details about the inviter

path Parameters
token
required
string

Token generated as a result of the user invite

Responses

Response samples

Content type
application/json
{
  • "inviter_user_name": "string",
  • "inviter_organisation_name": 0,
  • "target_organisation_name": 0
}

Create user from invite

Create a new user using an invite token

path Parameters
token
required
string

Token generated as a result of the user invite

Request Body schema: application/json
first_name
required
string

First name

last_name
required
string

Last name

phone_number
string

Phone number (preferably mobile)

password
required
string

The desired password

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "user_id": 0,
  • "username": "string",
  • "email": "string",
  • "organisation_id": 0,
  • "team_id": 0,
  • "first_name": "string",
  • "last_name": "string",
  • "features": [
    ],
  • "permissions": [
    ],
  • "is_staff": true
}

Request password reset

Request to reset an account's password via email.

Request Body schema: application/json
email
string

The email address of the account.

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Set password

Set a new account password.

Request Body schema: application/json
uid
required
integer

User ID of the account.

password
required
string

The desired password for the account.

token
required
string

The generated token used to verify the password reset.

Responses

Request samples

Content type
application/json
{
  • "uid": 0,
  • "password": "string",
  • "token": "string"
}

List allowed features Deprecated

List of allowed dashboard applications. DEPRECATED in favour of /api/account/access

Responses

Response samples

Content type
application/json
[
  • "myfarm",
  • "registration"
]

Get user access Deprecated

Returns all available features and permission levels for the requesting user. DEPRECATED in favour of /api/profile

Responses

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "permissions": [
    ]
}

List user training

Returns a list of training events attended by the given user

path Parameters
user_id
required
integer >= 1

id of the user whose training data should be fetched

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

year
integer

Year of the training when it was conducted

status
string
Default: "attended"
Enum: "attended" "absent" "registered"

Status of the user registration for a training

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Get user profile

Returns user profile information which includes team, organisation, name and all available features and permission levels for the requesting user

Responses

Response samples

Content type
application/json
{
  • "user_id": 0,
  • "username": "string",
  • "email": "string",
  • "organisation_id": 0,
  • "team_id": 0,
  • "first_name": "string",
  • "last_name": "string",
  • "features": [
    ],
  • "permissions": [
    ],
  • "is_staff": true
}

User team selection

A list of selected team summaries, mainly used so we can deliver relevant notifications.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

User team selection

A list of selected team IDs, mainly used so we can deliver relevant notifications.

Request Body schema: application/json
selected_team_ids
required
Array of integers

A list of selected team IDs.

Responses

Request samples

Content type
application/json
{
  • "selected_team_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "selected_team_ids": [
    ]
}

Submit feedback

Submit feedback on app functionality for our team to review

Request Body schema: application/json
comment
string

Comment to include with the user feedback (max 500 characters)

image
string

Screenshot of the associated page user is giving feedback for

star_rating
integer

Rating of the page, from 1 to 5

url
string

URL of the page the user is giving feedback for

submitted_by
integer

ID of the user submitting the feedback

submitted_at
string <date-time>

Datetime of submission - defaults to now

permission_to_contact
boolean

Whether the user is happy to be contacted about this feedback

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "image": "string",
  • "star_rating": 0,
  • "url": "string",
  • "submitted_by": 0,
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "permission_to_contact": true
}

Response samples

Content type
application/json
{
  • "comment": "string",
  • "image": "string",
  • "star_rating": 0,
  • "url": "string",
  • "submitted_by": 0,
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "permission_to_contact": true
}

Team

A team is a group of users: a user can belong to a single team.

Return a list of Teams

Returns a list of all teams for which the user is currently able to view any Plots or Storelots. A Team is added to the list if any of the following conditions are met:

  • The user is in the team
  • The organisation I am part of is connected to the organisation belonging to the team
  • An open plot that is owned by the team is visible to the users team. This could be because the user's team owns the plot, or because the plot has been shared with the user's team.
  • An open storelot that is owned by the team is visible to the user's team. This could be because the user's team created the storelot, grew the plot from which the storelot came, or shared the plot from which the storelot came with the user's team
  • The user has either SITE_ADMIN or REGISTRATION_ADMIN permission and has the same Site as the target Team
  • The user is KisanHub staff
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

page_size
integer [ 0 .. 100 ]
Default: 20

Page size. Use "0" for all results in a single page

search
string

Search for team by name

exclude_plot_shares
boolean
Default: false

Returns the team to which the user belongs.

only_plot_shares
boolean
Default: false

If true then only include teams that own Plots which are open & visible to the user; either because they belong to the user's team, or because they have been shared with the user's team.

only_storelot_shares
boolean
Default: false

If true then only include teams that own Storelots which are open & visible to the user; either because they belong to the user's team, or because they have been shared with the user's team.

only_shares
boolean
Default: false

If true then only include teams that own either Plots or Storelots which are open & visible to the user. This is already the default response for most users. This option is relevant to users with admin permissions and allows them to ignore their admin permissions and see only the teams from which data has been shared with them.

site_id
integer

Filters by Site ID

integration
string

Get all the teams who have subscribed to this integration

exclude_shared_with_plot
integer

Exclude any teams that this specific plot has been shared with.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create a new Team

Create a new Team. Only Kisanhub staff and enterprise users with SITE_ADMIN permission will be allowed to create teams.

Request Body schema: application/json
name
string

Team name

slug
string
Deprecated

Legacy identifier

site_id
integer
Deprecated

Teams are associated with a parent "Site". This is a legacy concept which will be replaced with a full organisational structure shortly.

global_gap_id
string

Global gap id of the lead user.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "slug": "string",
  • "site_id": 0,
  • "global_gap_id": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "slug": "string",
  • "lead": 1,
  • "site_id": 0,
  • "global_gap_id": "string",
  • "organisation_id": 1
}

Get team

Accessible teams will depend on the access rights of the requesting user. A user will always be able to view their own team, and teams that have shared plots with them. A user with the SITE_ADMIN permission in an Enterprise team will be able to view users of client teams. A Kisanhub staff member will be able to view all teams.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Team ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "slug": "string",
  • "lead": 1,
  • "site_id": 0,
  • "global_gap_id": "string",
  • "organisation_id": 1
}

Update an existing Team

Note that the team name must be globally unique

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Team ID

Request Body schema: application/json
name
string

Team name

slug
string
Deprecated

Legacy identifier

site_id
integer
Deprecated

Teams are associated with a parent "Site". This is a legacy concept which will be replaced with a full organisational structure shortly.

global_gap_id
string

Global gap id of the lead user.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "slug": "string",
  • "site_id": 0,
  • "global_gap_id": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "slug": "string",
  • "lead": 1,
  • "site_id": 0,
  • "global_gap_id": "string",
  • "organisation_id": 1
}

List team directory

Paginated list of all the teams in platform.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string"
}

Get team directory.

Summary of team from team directory.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Team ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string"
}

Farm

A farm in KisanHub owns a set of fields. It has a geographic location and an address, and is owned by a single team.

The following rules determine whether a particular user can edit or delete a farm:

  • The farm is owned by their team
  • The user has SITE_ADMIN permission and the team is associated with their Site
  • The user is a KisanHub staff member

A user can view a farm if any of the above rules are satisfied, or if one or more plots from fields in the farm have been shared with the user or their team.

List farms

Return a list of farms. A farm is included in the list if any of the following conditions are met:

  • The user is in the same team as the farm
  • The user's team is connected and can manage the farm team
  • The user originally created the Farm (e.g on behalf of a third party)
  • A plot from any fields owned by the farm has been shared with the users team, unless the exclude_plot_shares query parameter is set to "true"
  • The user is KisanHub staff
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

search
string
Example: search=my-plot

Text search

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

created_by_id
integer >= 1
Example: created_by_id=1

Filter by the user ID who created these entities

exclude_no_plots
boolean
Default: false

If true then exclude farms which have shared plots

exclude_plot_shares
boolean
Default: false

If true then exclude farms that are only visible due to Plot sharing

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create farm

Create a new farm. A team user with TEAM_ADMIN permission will be able to create a farm for their team. An enterprise user with SITE_ADMIN permission will be able to create a farm for a client team. A Kisanhub staff member can create farms for any team.

Request Body schema: application/json
name
required
string

Farm name

object (components-schemas-Address)
location
required
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

notes
string

Any notes related to the farm

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "location": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "slug": "string",
  • "name": "string",
  • "team_id": 1,
  • "address": {
    },
  • "location": [
    ],
  • "access": "read-edit",
  • "notes": "string",
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Deleted farms since a given date

List farm ids which have been deleted since a given date

query Parameters
from_date
required
string <date-time>

Include deleted farms from this date

Responses

Response samples

Content type
application/json
[
  • 0
]

GeoJSON farms

Farm summaries in GeoJSON format

query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

season
string
Deprecated
Example: season=2019/20

Growing season

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Get farm

Return a single farm by ID

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "slug": "string",
  • "name": "string",
  • "team_id": 1,
  • "address": {
    },
  • "location": [
    ],
  • "access": "read-edit",
  • "notes": "string",
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete farm

Delete a farm. Only farms with no attached fields can be deleted: an attempt to delete a farm with existing fields will result in a 409 error code.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Update farm

Update an existing farm. A team user with TEAM_ADMIN permission will be able to update a farm if it is owned by their team. An enterprise user with SITE_ADMIN permission will be able to update a farm for a client team. A Kisanhub staff member can update any farm.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Farm ID

Request Body schema: application/json
name
required
string

Farm name

object (components-schemas-Address)
location
required
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

notes
string

Any notes related to the farm

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "location": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "slug": "string",
  • "name": "string",
  • "team_id": 1,
  • "address": {
    },
  • "location": [
    ],
  • "access": "read-edit",
  • "notes": "string",
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get farm permission

Returns the permission level for this farm. A user has read/write access to a farm if any of the following conditions are met:

  • They are in the same Team as the Farm
  • The user has SITE_ADMIN or REGISTRATION_ADMIN access to the same Site as the Farm
  • The user is KisanHub staff

The user has read-only access to a farm only if they have access to any of the plots contained by any fields owned by this farm, and none of the above conditions apply.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "access": "read-edit",
  • "noDeleteReason": "string"
}

Field

A field corresponds to a bounded area of land that will be used to grow crops. In general fields are unchanged over time, since they represent real physical boundaries. A field will contain one or more plots.

List fields

Return a list of fields. The accessible fields depends on the request user permissions:

  • Kisanhub staff can see all fields
  • Farm owners (i.e users in the Team that owns the farm) can see all the farm fields
  • Users can see fields containing plots that have been shared with them or created by them
  • Users can see fields of connected manageable teams
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

search
string
Example: search=my-plot

Text search

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

created_by_id
integer >= 1
Example: created_by_id=1

Filter by the user ID who created these entities

off_platform
string
Enum: "only" "exclude"

If only then only returns "off-platform" fields· If exclude then exclude "off-platform" fields. If not specified then fields of both types are returned.

has_active_plots
boolean
Example: has_active_plots=true

If set then only include fields which have any active plots

genus_id
integer >= 1
Example: genus_id=2

Only include fields that have plots growing this genus

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create field

Create a new field. If a team user with TEAM_ADMIN can create fields for their own farm. An enterprise user with SITE_ADMIN permission may create fields for a farms owned by any of their client teams. A Kisanhub staff member may create a field for any farm.

Request Body schema: application/json
farm_id
required
integer >= 1

Farm ID if owned by a farm (i.e is "on-platform")

organisation_id
integer >= 1

Organisation ID if this is an off-platform field owned by an organisation

name
required
string

Field name

government_id
string

Governmental field identifier

soil_type_id
required
integer >= 1

Primary key

object (Boundary)

Bounding polygon

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

notes
string

Any notes related to the field

noDeleteReason
string

Describes why the entity cannot be deleted (usually because it contains other entities)

Responses

Request samples

Content type
application/json
{
  • "farm_id": 1,
  • "organisation_id": 1,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "boundary": {
    },
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "id": 1,
  • "slug": "string",
  • "access": "read-edit",
  • "farm_id": 1,
  • "organisation_id": 1,
  • "team_id": 0,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "region": "string",
  • "country_code": "st",
  • "boundary": {
    },
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Deleted fields since a given date

List field ids which have been deleted since a given date

query Parameters
from_date
required
string <date-time>

Include deleted fields from this date

Responses

Response samples

Content type
application/json
[
  • 0
]

Get field

Return a field

path Parameters
id
required
integer >= 1

Field primary key

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "id": 1,
  • "slug": "string",
  • "access": "read-edit",
  • "farm_id": 1,
  • "organisation_id": 1,
  • "team_id": 0,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "region": "string",
  • "country_code": "st",
  • "boundary": {
    },
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Delete field

Delete a field. Only fields with no attached plots can be deleted: an attempt to delete a field with any existing plots (including closed plots) will result in a 409 error code.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Update field

Update an existing field. If a team user with TEAM_ADMIN can update fields for their own farm. An enterprise user with SITE_ADMIN permission may update fields for a farms owned by any of their client teams. A Kisanhub staff member may update any field in any farm.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
farm_id
required
integer >= 1

Farm ID if owned by a farm (i.e is "on-platform")

organisation_id
integer >= 1

Organisation ID if this is an off-platform field owned by an organisation

name
required
string

Field name

government_id
string

Governmental field identifier

soil_type_id
required
integer >= 1

Primary key

object (Boundary)

Bounding polygon

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

notes
string

Any notes related to the field

noDeleteReason
string

Describes why the entity cannot be deleted (usually because it contains other entities)

Responses

Request samples

Content type
application/json
{
  • "farm_id": 1,
  • "organisation_id": 1,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "boundary": {
    },
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "id": 1,
  • "slug": "string",
  • "access": "read-edit",
  • "farm_id": 1,
  • "organisation_id": 1,
  • "team_id": 0,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "region": "string",
  • "country_code": "st",
  • "boundary": {
    },
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Get field permission

Returns the permission level for this field. A user has read/write access to a field if any of the following conditions are met:

  • They are in the same Team as the parent Farm
  • The user has SITE_ADMIN or REGISTRATION_ADMIN access to the same Site as the Farm
  • The user is KisanHub staff

The user has read-only access to a field only if they have access to any of the plots contained by the field, but none of the above conditions.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "access": "read-edit",
  • "noDeleteReason": "string"
}

List GeoJSON fields

Field summaries in GeoJSON format

query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

season
string
Deprecated
Example: season=2019/20

Growing season

bounds
Array of integers[ items = 4 characters ]
Example: bounds=-0.6287,53.8621,-0.5636,53.8830

Only return features that are contained within the bounding box (including intersects)

Format is xMin,yMin,xMax,yMax (i.e lng,lat NW / SE)

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Upload shapefile

Upload a ESRI GIS zipped field boundary shapefile

Request Body schema: multipart/form-data
file
string <binary>

Zipped ESRI shapefiles

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "names": [
    ]
}

Import shapefile

Creates fields for each polygon found in the ESRI zipped shapefile previously uploaded using the /api/field/shapefile/upload endpoint. Fields are added to a single Farm. This is an asynchronous operation: the caller can use /api/field/shapefile/import/{upload_id}/status to poll for status.

path Parameters
farm_id
required
integer >= 1

Farm primary key

upload_id
required
integer >= 1

ID of previously uploaded shapefile (returned from /api/field/shapefile/upload)

query Parameters
name_property
string
Default: "Name"

Use this property as the field name

Responses

Get shapefile upload status

path Parameters
upload_id
required
integer >= 1

ID of previously uploaded shapefile (returned from /api/field/shapefile/upload)

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "total": 0,
  • "completed": 0,
  • "errors": [
    ]
}

Plot

A plot describes a subdivision of a field that is planted with a particular crop variety. While this is modelled independently to operations the lifecycle of a plot is intimately connected with it's sowing and harvest operations. As such this API doesn't quite follow the same design pattern as elsewhere, since it allows the modification of sowing and harvest information: adding a planned or actual planting date will result in a new sowing operation being created, and similarly adding the planned or actual harvest date or yield will result in a new harvest operation being created (see operations). Editing existing dates and yields will edit the existing operation.

A planned sowing operation will be created by default for a new plot with the specified genus, variety and planting area. Todays date (with 00:00 time component) is taken as the start_date unless planned_planting_date is provided.

Plot operations can also be created and updated via operation API.

Plots can be shared/unshared with collaborating teams via the team-shares API. Only the team which own the plot, or the team of the owning plot (where they have allow_edit: true on their team-share) have the ability to share plots, no onward sharing past this is possible.

List plots

Return a paginated list of plots. By default we only return active plots i.e plots that have not been closed - use the "state" parameter to override this behaviour.

The plots that are accessible by the caller depends on a number of factors. Specifically a plot is visible for a user if any of the following conditions are met:

  • It is in the same team as the calling user (i.e the parent farm is in the same team as the caller)
  • The calling user is in the same team as the user that created the plot initially
  • The plot has explicitly been shared with the request user's team
  • The plot is associated with a existing trade record that is visible to the user
  • The caller has SITE_ADMIN permission and the plot is in a farm, owned by a Team associated with their Site
  • The caller is a KisanHub staff member
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

group_id
integer >= 1
Example: group_id=43

Filter by the organisation group ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

genus_ids
integer
Example: genus_ids=2,3

Comma-separated list of genus IDs. Includes plots that have planted any variety of any of these genera

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

variety_ids
Array of integers

Comma-separated list of variety variety IDs. Include plots that have planted any of these varieties.

tag_id
integer >= 1

Filter by crop tag ID. Include objects that have been tagged with this tag.

tag_ids
Array of integers
Example: tag_ids=2,3

Comma-separated list of crop tag IDs. Includes objects that have been tagged with any of these tags

crop_variety_id
integer >= 1
Deprecated
Example: crop_variety_id=1

Filter by the variety ID. Deprecated: use variety_id

growing_season
string
Example: growing_season=2020/21

Filter by growing season

created_by_id
integer >= 1
Example: created_by_id=1

Filter by the user ID who created these entities

slug
string
Deprecated

Search by the legacy "slug" identifier

search
string

Search for plot name

field_name
string

Return the plots associated with these fields.

is_active
boolean
Deprecated

If true then return the plots that are currently active i.e that have not been marked as harvested and closed. If false then only return the plots that have been harvested and closed i.e are not currently considered "active". If not specified then return plots disregarding the active state.

state
string
Enum: "all" "open" "closed"

If open then return the plots that are currently active i.e that have not been marked as closed (currently "active"). If closed then only return the plots that have been closed i.e that have been marked as closed (currently "inactive"). If all specified then return plots disregarding the active state. If not specified then returns open (currently "active") plots only.

status
string (PlotStatusValues)
Enum: "Ready to sample" "Awaiting results" "Resample" "Results received" "Resample results received" "Ready for harvest" "NOC" "Crop unsuitable" "Scheduled for harvest" "Harvested"

Filter by current plot status

sowing_from
string <date>
Example: sowing_from=2020-01-01

Filter results by sowing operation after a given date

sowing_to
string <date>
Example: sowing_to=2020-01-02

Filter results by sowing operation up to a given date

harvest_from
string <date>
Example: harvest_from=2020-01-01

Filter results by harvest operation after a given date

harvest_to
string <date>
Example: harvest_to=2020-01-02

Filter results by harvest operation up to a given date

off_platform
string
Enum: "only" "exclude"

If only then only returns "off-platform" plots· If exclude then exclude "off-platform" plots. If not specified that all plots are returned.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create a new plot

Create a new plot within a field. A user with TEAM_ADMIN will be able to create a new plot for their farm. An Enterprise user with SITE_ADMIN permission will be able to create a plot for any fields owned by any of their client teams. A Kisanhub staff user may create a plot for any field.

Request Body schema: application/json
field_id
required
integer (FieldId) >= 1

Field ID.

object (Boundary)

Bounding polygon

crop_id
required
integer (CropId) >= 1

Crop ("genus") ID. Note that value is taken from the most recent sowing operation.

name
string (PlotName)

Name. If this field is left blank while creating the plot, a name will be auto-generated in the format YYYY-0, where YYYY is current year.

slug
string
Deprecated

Legacy identifier

notes
string

Notes

variety_id
integer >= 1

Variety ID - see /api/variety for more detail

soil_type_id
integer >= 1

Soil type ID. If not specified then we assume the soil type of the field.

open
boolean

A plot is open when it is actively growing produce i.e it has not undergone a final harvest or been abandoned.

planned_planting_date
string <date-time>

Planned planting date. Editing this property will result in the creation of a new sowing operation

actual_planting_date
string <date-time>

Actual planting date. Editing this property will result in the creation of a new sowing operation

planting_area
number

The planting (i.e sown) area in ha. If not specified then we assume the working area is the full plot area as specified in bounds.area. Note that this is tied to the sown_area in the most recent sowing operation.

planned_harvest_date
string <date-time>

Planned harvest date. Editing this property will result in the creation of a new harvest operation, along with any planned_yield

planned_yield
number or null

Planned harvest yield, in t/ha. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

planned_quantity
number or null

Planned harvest quantity, in tonnes. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

actual_harvest_date
string <date-time>

Actual date of harvest. Editing this property will result in the creation of a new harvest operation, along with any actual_yield

actual_yield
number

Actual harvest yield, in t/ha. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

actual_quantity
number

Actual harvest quantity, in tonnes. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

object
Deprecated

Deprecated planting information. Please use planned_planting_date and actual_planting_date in preference: if either of those properties are specified then this section will be ignored.

object
Deprecated

Deprecated harvest information. Please use planned_harvest_date, planned_yield, actual_harvest_date and actual_yield in preference. If either of those properties are specified then this section will be ignored.

registration_code
string

A code that uniquely and globally identifies this plot

governmental_code
string

A country-specific code that uniquely identifies this plot

agronomist_ids
Array of integers

user ids list who are agronomists

owner_id
integer >= 1

The designated plot owner

growing_season
Array of strings

The growing season for this plot, like 2019/20. A plot can have more than one season

is_seed
boolean
Default: false

Is what's growing here for seed?

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

tag_ids
Array of integers

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "centroid": [
    ],
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "farm_id": 2,
  • "team_id": 1,
  • "organisation_id": 1,
  • "access": "read-edit",
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "tag_ids": [
    ],
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get plot by ID

get the plot identified by the ID in the URL

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "farm_id": 2,
  • "team_id": 1,
  • "organisation_id": 1,
  • "access": "read-edit",
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "tag_ids": [
    ],
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": "Ready to sample"
}

Delete plot

Delete the plot. Note that only plots which satisfy the following constraints may be deleted:

  • The plot has either no operations at all, or a single planned sowing operation only
  • The plot has no observations associated with it
path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Update plot

Update an existing plot within a field. A user with TEAM_ADMIN will be able to update any plot for their farm. A user with SITE_ADMIN permission will be able to update a plot for any fields owned by any of their client teams. A Kisanhub staff user may update any plot.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
field_id
required
integer (FieldId) >= 1

Field ID.

object (Boundary)

Bounding polygon

crop_id
required
integer (CropId) >= 1

Crop ("genus") ID. Note that value is taken from the most recent sowing operation.

name
string (PlotName)

Name. If this field is left blank while creating the plot, a name will be auto-generated in the format YYYY-0, where YYYY is current year.

slug
string
Deprecated

Legacy identifier

notes
string

Notes

variety_id
integer >= 1

Variety ID - see /api/variety for more detail

soil_type_id
integer >= 1

Soil type ID. If not specified then we assume the soil type of the field.

open
boolean

A plot is open when it is actively growing produce i.e it has not undergone a final harvest or been abandoned.

planned_planting_date
string <date-time>

Planned planting date. Editing this property will result in the creation of a new sowing operation

actual_planting_date
string <date-time>

Actual planting date. Editing this property will result in the creation of a new sowing operation

planting_area
number

The planting (i.e sown) area in ha. If not specified then we assume the working area is the full plot area as specified in bounds.area. Note that this is tied to the sown_area in the most recent sowing operation.

planned_harvest_date
string <date-time>

Planned harvest date. Editing this property will result in the creation of a new harvest operation, along with any planned_yield

planned_yield
number or null

Planned harvest yield, in t/ha. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

planned_quantity
number or null

Planned harvest quantity, in tonnes. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

actual_harvest_date
string <date-time>

Actual date of harvest. Editing this property will result in the creation of a new harvest operation, along with any actual_yield

actual_yield
number

Actual harvest yield, in t/ha. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

actual_quantity
number

Actual harvest quantity, in tonnes. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

object
Deprecated

Deprecated planting information. Please use planned_planting_date and actual_planting_date in preference: if either of those properties are specified then this section will be ignored.

object
Deprecated

Deprecated harvest information. Please use planned_harvest_date, planned_yield, actual_harvest_date and actual_yield in preference. If either of those properties are specified then this section will be ignored.

registration_code
string

A code that uniquely and globally identifies this plot

governmental_code
string

A country-specific code that uniquely identifies this plot

agronomist_ids
Array of integers

user ids list who are agronomists

owner_id
integer >= 1

The designated plot owner

growing_season
Array of strings

The growing season for this plot, like 2019/20. A plot can have more than one season

is_seed
boolean
Default: false

Is what's growing here for seed?

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

tag_ids
Array of integers

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "centroid": [
    ],
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "farm_id": 2,
  • "team_id": 1,
  • "organisation_id": 1,
  • "access": "read-edit",
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "tag_ids": [
    ],
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Partial plot update

Partially update an existing plot within a field. Only those properties supplied will be updated.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
name
string

Name. If this field is left blank while creating the plot, a name will be auto-generated in the format YYYY-0, where YYYY is current year.

field_id
integer (FieldId) >= 1

Field ID.

object (Boundary)

Bounding polygon

crop_id
integer (CropId) >= 1

Crop ("genus") ID. Note that value is taken from the most recent sowing operation.

slug
string
Deprecated

Legacy identifier

notes
string

Notes

variety_id
integer >= 1

Variety ID - see /api/variety for more detail

soil_type_id
integer >= 1

Soil type ID. If not specified then we assume the soil type of the field.

open
boolean

A plot is open when it is actively growing produce i.e it has not undergone a final harvest or been abandoned.

planned_planting_date
string <date-time>

Planned planting date. Editing this property will result in the creation of a new sowing operation

actual_planting_date
string <date-time>

Actual planting date. Editing this property will result in the creation of a new sowing operation

planting_area
number

The planting (i.e sown) area in ha. If not specified then we assume the working area is the full plot area as specified in bounds.area. Note that this is tied to the sown_area in the most recent sowing operation.

planned_harvest_date
string <date-time>

Planned harvest date. Editing this property will result in the creation of a new harvest operation, along with any planned_yield

planned_yield
number or null

Planned harvest yield, in t/ha. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

planned_quantity
number or null

Planned harvest quantity, in tonnes. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

actual_harvest_date
string <date-time>

Actual date of harvest. Editing this property will result in the creation of a new harvest operation, along with any actual_yield

actual_yield
number

Actual harvest yield, in t/ha. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

actual_quantity
number

Actual harvest quantity, in tonnes. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

object
Deprecated

Deprecated planting information. Please use planned_planting_date and actual_planting_date in preference: if either of those properties are specified then this section will be ignored.

object
Deprecated

Deprecated harvest information. Please use planned_harvest_date, planned_yield, actual_harvest_date and actual_yield in preference. If either of those properties are specified then this section will be ignored.

registration_code
string

A code that uniquely and globally identifies this plot

governmental_code
string

A country-specific code that uniquely identifies this plot

agronomist_ids
Array of integers

user ids list who are agronomists

owner_id
integer >= 1

The designated plot owner

created_at
string <date-time>

Date this plot was created

growing_season
Array of strings

The growing season for this plot, like 2019/20. A plot can have more than one season

is_seed
boolean
Default: false

Is what's growing here for seed?

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

tag_ids
Array of integers

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "centroid": [
    ],
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "farm_id": 2,
  • "team_id": 1,
  • "organisation_id": 1,
  • "access": "read-edit",
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "tag_ids": [
    ],
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get plot permission

Returns the permission level for this plot. A user has read access to a plot if any of the following conditions are met:

  • It is in their farm
  • The user has SITE_ADMIN access to the same Site as the Farm
  • The user has current read or read/write access via a team share to the Plot
  • The user is KisanHub staff

A user has read-only access only if the user has only read-only access to the associated plot via a team share.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "access": "read-edit",
  • "noDeleteReason": "string"
}

Update plot status

Update the status for a specific plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Request Body schema: application/json
status
string (PlotStatusValues)
Enum: "Ready to sample" "Awaiting results" "Resample" "Results received" "Resample results received" "Ready for harvest" "NOC" "Crop unsuitable" "Scheduled for harvest" "Harvested"

Plot status string

Responses

Request samples

Content type
application/json
{
  • "status": "Ready to sample"
}

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

List plot team shares

List of teams a plot has been shared with, and with what permissions

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Share a plot with a team

Share a plot with a team

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Request Body schema: application/json
allow_edit
boolean

The team has edit permissions on the plot

team_id
integer

Team ID

team_name
string

Team name

Responses

Request samples

Content type
application/json
{
  • "allow_edit": true,
  • "team_id": 1,
  • "team_name": "Team 2"
}

Response samples

Content type
application/json
{
  • "allow_edit": true,
  • "team_id": 1,
  • "team_name": "Team 2"
}

Remove team share

Remove a share from a team for a plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Request Body schema: application/json
team_id
integer

Responses

Request samples

Content type
application/json
{
  • "team_id": 1
}

List crop tags for a plot

List of crop tags on a plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

Add a crop tag to a plot

Add a tag to a plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Request Body schema: application/json
tag_id
integer >= 1

ID of the crop tag added to this plot

Responses

Request samples

Content type
application/json
{
  • "tag_id": 1
}

Response samples

Content type
application/json
{
  • "tag_id": "string",
  • "plot_id": 1
}

Remove a crop tag from a plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

tag_id
required
integer >= 1

Crop tag ID.

Responses

List crop tags assignable to this plot

List of crop tags assignable to this plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

List deleted plots

List plot ids which have been deleted since a given date

query Parameters
from_date
required
string <date-time>

Include deleted plots from this date

Responses

Response samples

Content type
application/json
[
  • 0
]

List GeoJSON plots

Plot summaries in GeoJSON format

query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

season
string
Deprecated
Example: season=2019/20

Growing season

bounds
Array of integers[ items = 4 characters ]
Example: bounds=-0.6287,53.8621,-0.5636,53.8830

Only return features that are contained within the bounding box (including intersects)

Format is xMin,yMin,xMax,yMax (i.e lng,lat NW / SE)

state
string
Enum: "all" "open" "closed"

If open then return the plots that are currently active i.e that have not been marked as closed (currently "active"). If closed then only return the plots that have been closed i.e that have been marked as closed (currently "inactive"). If all specified then return plots disregarding the active state. If not specified then returns open (currently "active") plots only.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

List varieties planted

Returns the set of varieties planted, grouped by genus

query Parameters
farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

growing_season
string
Example: growing_season=2020/21

Filter by growing season

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List possible plot status

Return the list of all possible plot status values

Responses

Response samples

Content type
application/json
[
  • "Ready to sample"
]

Get farmed regions

Returns a list of farm regions in which we have active plots.

query Parameters
from_date
string <date>
Example: from_date=2020-01-02T10:00:00Z

From date

to_date
string <date>
Example: to_date=2020-01-23T15:00:00Z

To date

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get plot team groups Deprecated

Returns a list of team-group associated with active plots teams.

query Parameters
from_date
string <date>
Example: from_date=2020-01-02T10:00:00Z

From date

to_date
string <date>
Example: to_date=2020-01-23T15:00:00Z

To date

Responses

Response samples

Content type
application/json
[
  • "string"
]

List plot genera

Returns the set of crops (i.e genus) and varieties planted

query Parameters
from_date
string <date>

Exclude plots harvested before this date

to_date
string <date>

Exclude plots planted after this date

region_name
string

Name of the region

team_group
string

Label of Team group

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Plot inventory report list

Return a human-readable report of the entire plot inventory.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

organisation_ids
integer
Example: organisation_ids=1,2,3

Comma-separated list of organisation IDs.

group_id
integer >= 1
Example: group_id=43

Filter by the organisation group ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

variety_ids
Array of integers

Comma-separated list of variety variety IDs. Include plots that have planted any of these varieties.

tag_id
integer >= 1

Filter by crop tag ID. Include objects that have been tagged with this tag.

tag_ids
Array of integers
Example: tag_ids=2,3

Comma-separated list of crop tag IDs. Includes objects that have been tagged with any of these tags

crop_variety_id
integer >= 1
Deprecated
Example: crop_variety_id=1

Filter by the variety ID. Deprecated: use variety_id

growing_season
string
Example: growing_season=2020/21

Filter by growing season

slug
string
Deprecated

Search by the legacy "slug" identifier

search
string

Search for plot name

field_name
string

Return the plots associated with these fields.

is_active
boolean
Deprecated

If true then return the plots that are currently active i.e that have not been marked as harvested and closed. If false then only return the plots that have been harvested and closed i.e are not currently considered "active". If not specified then return plots disregarding the active state.

status
string (PlotStatusValues)
Enum: "Ready to sample" "Awaiting results" "Resample" "Results received" "Resample results received" "Ready for harvest" "NOC" "Crop unsuitable" "Scheduled for harvest" "Harvested"

Filter by current plot status

state
string
Enum: "all" "open" "closed"

If open then return the plots that are currently active i.e that have not been marked as closed (currently "active"). If closed then only return the plots that have been closed i.e that have been marked as closed (currently "inactive"). If all specified then return plots disregarding the active state. If not specified then returns open (currently "active") plots only.

sowing_from
string <date>
Example: sowing_from=2020-01-01

Filter results by sowing operation after a given date

sowing_to
string <date>
Example: sowing_to=2020-01-02

Filter results by sowing operation up to a given date

harvest_from
string <date>
Example: harvest_from=2020-01-01

Filter results by harvest operation after a given date

harvest_to
string <date>
Example: harvest_to=2020-01-02

Filter results by harvest operation up to a given date

off_platform
string
Enum: "only" "exclude"

If only then only returns "off-platform" plots· If exclude then exclude "off-platform" plots. If not specified that all plots are returned.

format
string
Default: "json"
Enum: "csv" "json"
Example: format=csv

Change the output format. Defaults to JSON

Responses

Response samples

Content type
{
  • "total": 0,
  • "crop_type_count": 0,
  • "results": [
    ]
}

Get plot inventory statistics

Return aggregated totals for various metrics for the matching set of plots

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

crop_variety_id
integer >= 1
Deprecated
Example: crop_variety_id=1

Filter by the variety ID. Deprecated: use variety_id

growing_season
string
Example: growing_season=2020/21

Filter by growing season

slug
string
Deprecated

Search by the legacy "slug" identifier

search
string

Search for plot name

field_name
string

Return the plots associated with these fields.

is_active
boolean
Deprecated

If true then return the plots that are currently active i.e that have not been marked as harvested and closed. If false then only return the plots that have been harvested and closed i.e are not currently considered "active". If not specified then return plots disregarding the active state.

status
string (PlotStatusValues)
Enum: "Ready to sample" "Awaiting results" "Resample" "Results received" "Resample results received" "Ready for harvest" "NOC" "Crop unsuitable" "Scheduled for harvest" "Harvested"

Filter by current plot status

state
string
Enum: "all" "open" "closed"

If open then return the plots that are currently active i.e that have not been marked as closed (currently "active"). If closed then only return the plots that have been closed i.e that have been marked as closed (currently "inactive"). If all specified then return plots disregarding the active state. If not specified then returns open (currently "active") plots only.

sowing_from
string <date>
Example: sowing_from=2020-01-01

Filter results by sowing operation after a given date

sowing_to
string <date>
Example: sowing_to=2020-01-02

Filter results by sowing operation up to a given date

harvest_from
string <date>
Example: harvest_from=2020-01-01

Filter results by harvest operation after a given date

harvest_to
string <date>
Example: harvest_to=2020-01-02

Filter results by harvest operation up to a given date

off_platform
string
Enum: "only" "exclude"

If only then only returns "off-platform" plots· If exclude then exclude "off-platform" plots. If not specified that all plots are returned.

Responses

Response samples

Content type
application/json
{
  • "farms": 4,
  • "plots": 23,
  • "cropped_area": 11.52,
  • "planted_plots": 22,
  • "harvested_plots": 20,
  • "expected_production": 55.5
}

Genus

Crop genus

List genera

Returns a list of available genera (often called "crop"). Names are translated according to the Accept-Language header, defaulting to English.

query Parameters
crop_name
string
Example: crop_name=Potato

Filter by the genus name

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get crop genus

Returns a single genus (often called "crop"). Names are translated according to the Accept-Language header, defaulting to English.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "colour_code": "string",
  • "is_perennial": true
}

Get growth stages for genera

Returns lists of primary and secondary growth stages associated with each genus

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get growth stage for genus

Returns a list of primary and secondary growth stages associated with a given genus

path Parameters
genus_id
required
integer (PrimaryKey) >= 1
Example: 1

ID

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "primary_growth_stages": [
    ]
}

Variety

Crop variety

List varieties

Return an unpaginated list of available crop varieties. Names are translated according to the Accept-Language header, defaulting to English.

query Parameters
genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create variety

Create a new crop variety. Uniqness is enforced for the name (for the given genus). Only available to users with VARIETY_ADMIN permission or KisanHub staff.

Request Body schema: application/json
name
string

Name

crop_id
integer >= 1

Genus ID - see /api/genus for more detail

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "crop_id": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "crop_id": 1
}

List varieties - paginated

Return an paginated list of available crop varieties. Names are translated according to the Accept-Language header, defaulting to English.

query Parameters
genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Variety report

List varieties with their associated genus

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get variety

Return a single variety. Names are translated according to the Accept-Language header, defaulting to English.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "crop_id": 1
}

Growth stage

Crop-specific growth stages

List primary growth stages

Return all primary growth stages for all visible genera. Names are translated according to the Accept-Language header, defaulting to English.

query Parameters
genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get primary growth stage

Return a primary growth stage. The name is translated according to the Accept-Language header, defaulting to English.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "code": "PGS 01",
  • "name": "Vegetative growth",
  • "local_name": "Vegetative growth",
  • "genus_id": 2
}

List primary growth stages with translations

Return all primary growth stages for all visible genera. Names are supplied in all available languages

query Parameters
genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a primary growth stages translations

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
code
string

Shortcode

required
object (Translations)

Translations for a single text string

genus_id
required
integer (GenusId) >= 1

Genus ID

Responses

Request samples

Content type
application/json
{
  • "code": "PGS 01",
  • "name": {
    },
  • "genus_id": 2
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "code": "PGS 01",
  • "name": {
    },
  • "genus_id": 2
}

List secondary growth stages

Return all secondary growth stages for all visible primary growth stages. Names are translated according to the Accept-Language header, defaulting to English.

query Parameters
primary_growth_stage_id
integer >= 1
Example: primary_growth_stage_id=1

Filter by the primary growth stage

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get secondary growth stage

Return a secondary growth stage. The name is translated according to the Accept-Language header, defaulting to English.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "code": "SGS 10",
  • "name": "First leaves begin to extend",
  • "local_name": "First leaves begin to extend",
  • "has_field_coverage": false
}

List secondary growth stages with translations

Return all secondary growth stages. Names are supplied in all available languages

query Parameters
string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a secondary growth stages translation

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
code
string

Shortcode

required
object (Translations)

Translations for a single text string

genus_id
integer (GenusId) >= 1

Genus ID

has_field_coverage
boolean (HasFieldCoverage)

If true then field coverage is applicable

Responses

Request samples

Content type
application/json
{
  • "code": "SGS 01",
  • "name": {
    },
  • "genus_id": 2,
  • "has_field_coverage": false
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "code": "SGS 01",
  • "name": {
    },
  • "genus_id": 2,
  • "has_field_coverage": false
}

Get growth stages for genera

Returns lists of primary and secondary growth stages associated with each genus

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get growth stage for genus

Returns a list of primary and secondary growth stages associated with a given genus

path Parameters
genus_id
required
integer (PrimaryKey) >= 1
Example: 1

ID

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "primary_growth_stages": [
    ]
}

Operations

Field and plot operations

List operations

Return a paginated list of operations of all types, in ascending order of when the operation was last updated (we set the creation date as the initial update date for convenience). Only observations from open plots are listed by default: to override this set the include_closed_plots parameter to "true".

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 1000 ]
Default: 20

Page size

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

plot_id
integer >= 1

Only return operations for this Plot

field_id
integer >= 1

Only return operations for this Field

farm_id
integer >= 1

Only return operations for this Farm

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

exclude_linked_planned
boolean

If true then don't return planned operations which have associated applied operations

include_closed_plots
boolean

If True, then returns operations of closed/inactive plots also. Defaults to False

status
string (OperationStatus)
Enum: "upcoming" "overdue" "completed"

Operation status

type
Array of strings (OperationCategory)
Items Enum: "fertiliser" "pesticide" "sowing" "harvest" "irrigation" "intercultural" "land_preparation"
Example: type=sowing,harvest

Filter by operation type. Multiple values can be specified - operations matching any of the types specified will be returned

applied
boolean

If true then filter for applied operations only. If false then filter for planned operations only. The default is to return all operations, irrespective of planning status.

ordering
string
Enum: "created_at" "updated_at" "start_date"
Example: ordering=-created_at,updated_at

Comma separated field names to order by. Prefix with - for descending.

search
string
Example: search=growercorp

Search for operations by team or plot name

product_subtype
string
Enum: "organic" "inorganic" "herbicide" "insecticide" "nematicide" "fungicide" "adjuvant" "seed treatment" "growth regulator" "molluscicide"

Filter all product-based operations by the specified subtype

is_burndown
boolean

If true then only return pesticide burndown operations

from_date
string <date>
Example: from_date=2020-01-02

Only include operations completed at or after this date

to_date
string <date>
Example: to_date=2020-01-06

Only include operations completed at or before this date

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create operation

Create a new operation

Request Body schema: application/json
type
required
string (OperationCategory)

Operation type

notes
string

Supplemental notes

start_date
required
string <date>

Operation started on this date. If not specified then this date will be set to the end_date. Note that either start_date or end_date must be specified. Note that while for convenience we will accept dates in full ISO datetime format, only the date component is used.

end_date
string <date>

Operation ended on this datetime. If not specified then this date will be set with the start_date. Note that while for convenience we will accept dates in full ISO datetime format, only the date component is used.

plot_id
required
integer >= 1

Plot ID

team_id
integer (TeamId) >= 1

Team ID

is_applied
required
boolean
Default: true

If false then this is a planned operation i.e an operation that is scheduled to happen. If true then the operation actually happened

created_at
string <date-time>

When this operation was created

updated_at
string <date-time>

When this operation was updated. This will be equal to the created_at date initially

Array of objects (Attachments)
planned_operation_id
integer

For applied operations this may optionally link to a related planned operation of the same type and plot.

slug
string
Deprecated

Legacy operation slug

method
string
Enum: "broadcasting" "placement" "fertigation" "foliar-spray" "injection" "drenching"

Method of application

Array of objects (AppliedProduct)

List of applied fertiliser products

primary_growth_stage_id
number >= 1

The primary growth stage of the plot.

primary_growth_stage_name
number (PrimaryGrowthStageId) >= 1

The primary growth stage of the plot.

secondary_growth_stage_id
number >= 1

The secondary growth stage of the plot, which is dependent on the primary growth stage.

secondary_growth_stage_name
number (SecondaryGrowthStageId) >= 1

The secondary growth stage of the plot, which is dependent on the primary growth stage.

percent_field_cover
number <float> [ 0 .. 100 ]

Percentage area of plot that has reached the above primary and secondary growth stages

Responses

Request samples

Content type
application/json
Example
{
  • "type": "fertiliser",
  • "notes": "string",
  • "start_date": "2020-01-02",
  • "end_date": "2020-01-02",
  • "plot_id": 1,
  • "team_id": 6,
  • "is_applied": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "attachments": [],
  • "planned_operation_id": 0,
  • "slug": "string",
  • "method": "broadcasting",
  • "products": [
    ],
  • "primary_growth_stage_id": 1,
  • "primary_growth_stage_name": 1,
  • "secondary_growth_stage_id": 1,
  • "secondary_growth_stage_name": 1,
  • "percent_field_cover": 100
}

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "type": "fertiliser",
  • "notes": "string",
  • "start_date": "2020-01-02",
  • "end_date": "2020-01-02",
  • "plot_id": 1,
  • "plot_name": "My plot",
  • "field_id": 1,
  • "field_name": "North field",
  • "farm_id": 1,
  • "farm_name": "Sunny Farm",
  • "team_id": 6,
  • "team_name": "My Team",
  • "is_applied": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "created_by_name": "string",
  • "updated_by_id": 1,
  • "updated_by_name": "string",
  • "attachments": [],
  • "planned_operation_id": 0,
  • "status": "upcoming",
  • "slug": "string",
  • "method": "broadcasting",
  • "products": [
    ],
  • "primary_growth_stage_id": 1,
  • "primary_growth_stage_name": 1,
  • "secondary_growth_stage_id": 1,
  • "secondary_growth_stage_name": 1,
  • "percent_field_cover": 100
}

Get operation

Return a single operation

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "type": "fertiliser",
  • "notes": "string",
  • "start_date": "2020-01-02",
  • "end_date": "2020-01-02",
  • "plot_id": 1,
  • "plot_name": "My plot",
  • "field_id": 1,
  • "field_name": "North field",
  • "farm_id": 1,
  • "farm_name": "Sunny Farm",
  • "team_id": 6,
  • "team_name": "My Team",
  • "is_applied": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "created_by_name": "string",
  • "updated_by_id": 1,
  • "updated_by_name": "string",
  • "attachments": [],
  • "planned_operation_id": 0,
  • "status": "upcoming",
  • "slug": "string",
  • "method": "broadcasting",
  • "products": [
    ],
  • "primary_growth_stage_id": 1,
  • "primary_growth_stage_name": 1,
  • "secondary_growth_stage_id": 1,
  • "secondary_growth_stage_name": 1,
  • "percent_field_cover": 100
}

Update operation

Update an existing operation

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
type
required
string (OperationCategory)

Operation type

notes
string

Supplemental notes

start_date
required
string <date>

Operation started on this date. If not specified then this date will be set to the end_date. Note that either start_date or end_date must be specified. Note that while for convenience we will accept dates in full ISO datetime format, only the date component is used.

end_date
string <date>

Operation ended on this datetime. If not specified then this date will be set with the start_date. Note that while for convenience we will accept dates in full ISO datetime format, only the date component is used.

plot_id
required
integer >= 1

Plot ID

team_id
integer (TeamId) >= 1

Team ID

is_applied
required
boolean
Default: true

If false then this is a planned operation i.e an operation that is scheduled to happen. If true then the operation actually happened

created_at
string <date-time>

When this operation was created

updated_at
string <date-time>

When this operation was updated. This will be equal to the created_at date initially

Array of objects (Attachments)
planned_operation_id
integer

For applied operations this may optionally link to a related planned operation of the same type and plot.

slug
string
Deprecated

Legacy operation slug

method
string
Enum: "broadcasting" "placement" "fertigation" "foliar-spray" "injection" "drenching"

Method of application

Array of objects (AppliedProduct)

List of applied fertiliser products

primary_growth_stage_id
number >= 1

The primary growth stage of the plot.

primary_growth_stage_name
number (PrimaryGrowthStageId) >= 1

The primary growth stage of the plot.

secondary_growth_stage_id
number >= 1

The secondary growth stage of the plot, which is dependent on the primary growth stage.

secondary_growth_stage_name
number (SecondaryGrowthStageId) >= 1

The secondary growth stage of the plot, which is dependent on the primary growth stage.

percent_field_cover
number <float> [ 0 .. 100 ]

Percentage area of plot that has reached the above primary and secondary growth stages

Responses

Request samples

Content type
application/json
Example
{
  • "type": "fertiliser",
  • "notes": "string",
  • "start_date": "2020-01-02",
  • "end_date": "2020-01-02",
  • "plot_id": 1,
  • "team_id": 6,
  • "is_applied": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "attachments": [],
  • "planned_operation_id": 0,
  • "slug": "string",
  • "method": "broadcasting",
  • "products": [
    ],
  • "primary_growth_stage_id": 1,
  • "primary_growth_stage_name": 1,
  • "secondary_growth_stage_id": 1,
  • "secondary_growth_stage_name": 1,
  • "percent_field_cover": 100
}

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "type": "fertiliser",
  • "notes": "string",
  • "start_date": "2020-01-02",
  • "end_date": "2020-01-02",
  • "plot_id": 1,
  • "plot_name": "My plot",
  • "field_id": 1,
  • "field_name": "North field",
  • "farm_id": 1,
  • "farm_name": "Sunny Farm",
  • "team_id": 6,
  • "team_name": "My Team",
  • "is_applied": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "created_by_name": "string",
  • "updated_by_id": 1,
  • "updated_by_name": "string",
  • "attachments": [],
  • "planned_operation_id": 0,
  • "status": "upcoming",
  • "slug": "string",
  • "method": "broadcasting",
  • "products": [
    ],
  • "primary_growth_stage_id": 1,
  • "primary_growth_stage_name": 1,
  • "secondary_growth_stage_id": 1,
  • "secondary_growth_stage_name": 1,
  • "percent_field_cover": 100
}

Delete operation

Delete the operation, along with any linked operation (i.e delete both planned and applied)

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Get operation permission

Returns the permission level for this operation. A user has read/write access to an operation if any of the following conditions are met:

  • It was initially created by a member of their team
  • It is in their farm
  • The user has SITE_ADMIN access to the same Site as the Farm
  • The user has current read or read/write access to the Plot
  • The user is KisanHub staff

A user has only read-only access if the user has only read-only access to the associated plot.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "access": "read-edit",
  • "noDeleteReason": "string"
}

Create operation report async

Create an operation report. This is an asynchronous operation since reports may be large: the URL containing the created report will be found using get-report-status. Note that this API takes all the same query parameters as the list operations API, but as body data.

Responses

Response samples

Content type
application/json
{
  • "token": "string"
}

Get operation report status

path Parameters
token
required
string

Responses

Response samples

Content type
application/json
{
  • "url": "string"
}

Operation schedules

An operation schedule defines a set of planned operations that will be automatically created after a specified trigger operation. A trigger is a combination of genus/variety and organisation group, and the only trigger operation currently supported is a sowing operation i.e the scheduled operations will be added to a plot if it matches the trigger criteria immediately after an actually sowing operation is created for that plot.

List crop schedules

List crop schedules

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create crop schedule

Create a crop schedule. Only availble to KisanHub staff and users with the REGISTRATION_ADMIN permission

Request Body schema: application/json
name
required
string

Name

owner_id
integer

Owning organisation ID. Only allowed for staff users

is_active
boolean

True if active

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "owner_id": 0,
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "owner_id": 0,
  • "is_active": true
}

Get crop schedule

Get a crop schedule

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "owner_id": 0,
  • "is_active": true
}

List crop schedule operation

List crop schedule operations

query Parameters
qualifier_id
integer

Filter by parent schedule qualifier ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create crop schedule operation

List crop schedule operations

Request Body schema: application/json
qualifier_id
required
integer
days_after_sowing
integer >= 0

qualifier is fired N days after an actual sowing operation

type
string (OperationCategory)
Enum: "fertiliser" "pesticide" "sowing" "harvest" "irrigation" "intercultural" "land_preparation"

Operation type

method
string

Operation method

primary_growth_stage_id
number (PrimaryGrowthStageId) >= 1

The primary growth stage of the plot.

secondary_growth_stage_id
number (SecondaryGrowthStageId) >= 1

The secondary growth stage of the plot, which is dependent on the primary growth stage.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "qualifier_id": 0,
  • "days_after_sowing": 0,
  • "type": "pesticide",
  • "method": "fertigation",
  • "primary_growth_stage_id": 1,
  • "secondary_growth_stage_id": 1,
  • "projects": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "qualifier_id": 0,
  • "days_after_sowing": 0,
  • "type": "pesticide",
  • "method": "fertigation",
  • "primary_growth_stage_id": 1,
  • "primary_growth_stage_name": "Germination",
  • "secondary_growth_stage_id": 1,
  • "secondary_growth_stage_name": "Seed imbibition complete",
  • "projects": [
    ]
}

Get crop schedule operation

Get crop schedule operation

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Product

Fertiliser / pesticides

List active ingredients

List active ingredients used by pesticides

query Parameters
string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

search
string

Search for ingredient by name

product_id
integer

Filter for ingredients used by this product

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create active ingredient

Note that curation of the list of active ingredients is managed by KisanHub. As such this operation is only accessible for KisanHub staff.

Request Body schema: application/json
name
string

Name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string"
}

Get active ingredient

Return a single active ingredient

path Parameters
id
required
integer

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string"
}

List products

Return a list of fertiliser and pesticide products

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

search
string

Search by product or active ingredient name

type
any
Enum: "pesticide" "fertiliser"

Product type

subtype
string (ProductSubTypes)
Enum: "herbicide" "insecticide" "nematicide" "fungicide" "adjuvant" "seed treatment" "growth regulator" "molluscicide" "organic" "inorganic"

Product subtype

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create product

Note that curation of the list of pesticide products is managed by KisanHub. As such this operation is only accessible for KisanHub staff.

Request Body schema: application/json
name
required
string

Name

manufacturer
string

Manufacturer name

type
required
string

type

state
string
Enum: "liquid" "solid" "unknown"

Product state. If liquid then it can be assumed that the associated application rate unit is l/ha. If solid then we use kg/ha. We cannot infer units for unknown (but it will be either kg/ha or l/ha)

is_public
boolean
Default: true

If false then this product is only visible to the Team that created it

subtype
string (FertiliserSubTypes)
Enum: "organic" "inorganic"
nitrogen
number [ 0 .. 100 ]

Nitrogen percentage

phosphorus
number [ 0 .. 100 ]

Phosphorus percentage

potassium
number [ 0 .. 100 ]

Potassium percentage

magnesium
number [ 0 .. 100 ]

Magnesium percentage

calcium
number [ 0 .. 100 ]

Calcium percentage

sulphur
number [ 0 .. 100 ]

Sulphur percentage

zinc
number [ 0 .. 100 ]

Zinc percentage

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "manufacturer": "string",
  • "type": "fertiliser",
  • "state": "liquid",
  • "is_public": true,
  • "subtype": "organic",
  • "nitrogen": 100,
  • "phosphorus": 100,
  • "potassium": 100,
  • "magnesium": 100,
  • "calcium": 100,
  • "sulphur": 100,
  • "zinc": 100
}

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "name": "string",
  • "manufacturer": "string",
  • "type": "fertiliser",
  • "state": "liquid",
  • "is_public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "subtype": "organic",
  • "nitrogen": 100,
  • "phosphorus": 100,
  • "potassium": 100,
  • "magnesium": 100,
  • "calcium": 100,
  • "sulphur": 100,
  • "zinc": 100
}

Get product

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "name": "string",
  • "manufacturer": "string",
  • "type": "fertiliser",
  • "state": "liquid",
  • "is_public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "subtype": "organic",
  • "nitrogen": 100,
  • "phosphorus": 100,
  • "potassium": 100,
  • "magnesium": 100,
  • "calcium": 100,
  • "sulphur": 100,
  • "zinc": 100
}

Update product

Note that curation of the list of pesticide products is managed by KisanHub. As such this operation is only accessible for KisanHub staff.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
name
required
string

Name

manufacturer
string

Manufacturer name

type
required
string

type

state
string
Enum: "liquid" "solid" "unknown"

Product state. If liquid then it can be assumed that the associated application rate unit is l/ha. If solid then we use kg/ha. We cannot infer units for unknown (but it will be either kg/ha or l/ha)

is_public
boolean
Default: true

If false then this product is only visible to the Team that created it

subtype
string (FertiliserSubTypes)
Enum: "organic" "inorganic"
nitrogen
number [ 0 .. 100 ]

Nitrogen percentage

phosphorus
number [ 0 .. 100 ]

Phosphorus percentage

potassium
number [ 0 .. 100 ]

Potassium percentage

magnesium
number [ 0 .. 100 ]

Magnesium percentage

calcium
number [ 0 .. 100 ]

Calcium percentage

sulphur
number [ 0 .. 100 ]

Sulphur percentage

zinc
number [ 0 .. 100 ]

Zinc percentage

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "manufacturer": "string",
  • "type": "fertiliser",
  • "state": "liquid",
  • "is_public": true,
  • "subtype": "organic",
  • "nitrogen": 100,
  • "phosphorus": 100,
  • "potassium": 100,
  • "magnesium": 100,
  • "calcium": 100,
  • "sulphur": 100,
  • "zinc": 100
}

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "name": "string",
  • "manufacturer": "string",
  • "type": "fertiliser",
  • "state": "liquid",
  • "is_public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "subtype": "organic",
  • "nitrogen": 100,
  • "phosphorus": 100,
  • "potassium": 100,
  • "magnesium": 100,
  • "calcium": 100,
  • "sulphur": 100,
  • "zinc": 100
}

List products with all ingredients expanded

Return a list of fertiliser and pesticide products with pesticide ingredients expanded

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

search
string

Search by product and active ingredient name

type
any
Enum: "pesticide" "fertiliser"

Product type

subtype
string (ProductSubTypes)
Enum: "herbicide" "insecticide" "nematicide" "fungicide" "adjuvant" "seed treatment" "growth regulator" "molluscicide" "organic" "inorganic"

Product subtype

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Plot share

Plot sharing

List plot shares

Returns a list of team shares of plots that belong to the user's primary team, or created by a user from his primary team

query Parameters
plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 0 .. 100 ]
Default: 20

Page size. Use "0" for all results in a single page

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create plot share

Creates a team share object for a given plot and permission level

Request Body schema: application/json
plot_id
required
integer (PlotId) >= 1

Plot ID

team_id
required
integer (TeamId) >= 1

Team ID

Responses

Request samples

Content type
application/json
{
  • "plot_id": 4,
  • "team_id": 6
}

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

Get plot share by id

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Id of the observation

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "plot_id": 4,
  • "team_id": 6,
  • "permission": "read-edit",
  • "team_name": "string"
}

Update permission of a plot share

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Id of the observation

Request Body schema: application/json

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": 1,
  • "plot_id": 4,
  • "team_id": 6,
  • "permission": "read-edit",
  • "team_name": "string"
}

Delete plot share by id

Delete a plot team share that belongs to the user's plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Id of the observation

Responses

Soil type

Soil type

List soil types

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get soil type

Return a single soil type by ID

path Parameters
id
required
integer >= 1

Soil type ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "description": "string"
}

Soil testing

Soil testing

Get list of soil report laboratories

Returns a list of laboratories of the soil category which are used in soil reports.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a soil report laboratory

Returns a laboratory of the soil category.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

id

Responses

Response samples

Content type
application/json
{ }

List soil samples

Return a list of soil samples

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

search
string

Search for sample name

exclude_with_reports
boolean

If true then exclude samples which already have reports

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create soil sample

Request Body schema: application/json
name
string

Name

field_id
integer >= 1

Field ID

date
string <date-time>
location
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

depth
number

Depth in mm

notes
string

Associated notes

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "field_id": 1,
  • "date": "2019-08-24T14:15:22Z",
  • "location": [
    ],
  • "depth": 0,
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "field_id": 1,
  • "date": "2019-08-24T14:15:22Z",
  • "location": [
    ],
  • "depth": 0,
  • "notes": "string"
}

GeoJSON soil samples

Soil sample summaries in GeoJSON format

query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

season
string
Deprecated
Example: season=2019/20

Growing season

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Get soil sample

path Parameters
id
required
integer >= 1

Soil sample ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "field_id": 1,
  • "date": "2019-08-24T14:15:22Z",
  • "location": [
    ],
  • "depth": 0,
  • "notes": "string"
}

List soil test reports.

Return a paginated list of soil test reports.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

sample_id
integer >= 1

Filter by sample id

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create soil test report

Request Body schema: application/json
id
integer >= 1

Soil report ID

date
string <date-time>

Test report creation or most recent update

notes
string

Associated notes

Array of objects (Attachments)
object

Physical soil properties

object

Chemical properties

object

Micronutrients

object

Macronutrients

laboratory_id
required
integer >= 1

Laboratory ID

sample_id
required
integer >= 1

Soil sample ID

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "date": "2019-08-24T14:15:22Z",
  • "notes": "string",
  • "attachments": [],
  • "physical_properties": {
    },
  • "chemical_properties": {
    },
  • "micro_nutrients": {
    },
  • "macro_nutrients": {
    },
  • "laboratory_id": 1,
  • "sample_id": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "date": "2019-08-24T14:15:22Z",
  • "notes": "string",
  • "attachments": [],
  • "physical_properties": {
    },
  • "chemical_properties": {
    },
  • "micro_nutrients": {
    },
  • "macro_nutrients": {
    },
  • "laboratory_id": 1,
  • "field_id": 0,
  • "sample_id": 1
}

Get soil report

path Parameters
id
required
integer >= 1

Soil report ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "date": "2019-08-24T14:15:22Z",
  • "notes": "string",
  • "attachments": [],
  • "physical_properties": {
    },
  • "chemical_properties": {
    },
  • "micro_nutrients": {
    },
  • "macro_nutrients": {
    },
  • "laboratory_id": 1,
  • "field_id": 0,
  • "sample_id": 1
}

Update soil report

path Parameters
id
required
integer >= 1

Soil report ID

Request Body schema: application/json
id
required
integer >= 1

Soil report ID

date
string <date-time>

Test report creation or most recent update

notes
string

Associated notes

Array of objects (Attachments)
object

Physical soil properties

object

Chemical properties

object

Micronutrients

object

Macronutrients

laboratory_id
required
integer >= 1

Laboratory ID

sample_id
required
integer >= 1

Soil sample ID

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "date": "2019-08-24T14:15:22Z",
  • "notes": "string",
  • "attachments": [],
  • "physical_properties": {
    },
  • "chemical_properties": {
    },
  • "micro_nutrients": {
    },
  • "macro_nutrients": {
    },
  • "laboratory_id": 1,
  • "sample_id": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "date": "2019-08-24T14:15:22Z",
  • "notes": "string",
  • "attachments": [],
  • "physical_properties": {
    },
  • "chemical_properties": {
    },
  • "micro_nutrients": {
    },
  • "macro_nutrients": {
    },
  • "laboratory_id": 1,
  • "field_id": 0,
  • "sample_id": 1
}

List soil test reports summaries

Return a paginated list of soil test report summaries.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

sample_id
integer >= 1

Filter by sample id

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Crop quality

A system to allow users to define the different parameters they wish to test on their crops and then record results to them. Threshold levels can be set for individual markets for each test parameter, with market suitability automatically being calculated when results are submitted.

List assessments

Paginated list of crop quality assessments

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

lot_id
integer >= 1
Example: lot_id=3

Filter by the store-lot ID

template_id
integer >= 1
Example: template_id=3

Filter by the template ID

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create assessment

Create a crop quality assessment for an existing or an off platform field or lot. You can create an "off-platform" crop by providing a new_field_name (for an off-platform field), and/or a new_lot_name (for an off-platform store lot). When creating an off-platform field the caller must create an off-platform lot: however an on-platform field may be paired with an off-platform lot. Off-platform fields must specify both region and country of origin

The returned assessment will contain information on specification suitability.

If associated with a plot the plot status will be changed to RESULTS_RECEIVED if test results have been supplied and AWAITING_RESULT if no results have been applied, but only if the status is currently none of the following:

  • READY_FOR_HARVEST
  • NOC
  • CROP_UNSUITABLE
  • SCHEDULED_FOR_HARVEST
  • HARVESTED
Request Body schema: application/json
One of
Any of
lot_id
required
integer >= 1

Store lot ID

template_id
required
integer (TemplateId)

Template API

sample_reference
string (SampleReference)

Sample reference

sample_date
required
string or null <date> (SampleDate)

Sample date of Assessment

Array of objects (CustomFieldValues)

List of Custom Field values

required
Array of objects (TestResultsV2)

Values collected

Array of objects (Attachments)
Array of objects (SubSample)

List of potential subsamples. Each test result may be associated with a specific subsample, referred to by index into this list

Responses

Request samples

Content type
application/json
{
  • "template_id": 2,
  • "sample_reference": "Sample 101",
  • "sample_date": "2019-02-25",
  • "custom_field_values": [
    ],
  • "test_results": [
    ],
  • "attachments": [],
  • "sub_samples": [
    ],
  • "plot_id": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "template_id": 2,
  • "suitability": [
    ],
  • "sample_reference": "Sample 101",
  • "sample_date": "2019-02-25",
  • "custom_field_values": [
    ],
  • "test_results": [
    ],
  • "attachments": [],
  • "sub_samples": [
    ],
  • "plot_id": 1,
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List assessment reports

Get shared assessment reports

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

lot_id
integer >= 1
Example: lot_id=3

Filter by the store-lot ID

template_id
integer >= 1
Example: template_id=3

Filter by the template ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "template": {
    },
  • "crop_name": "string",
  • "owner_organisation_name": "string",
  • "field_name": "North field",
  • "variety_name": "Accord",
  • "suitability": [
    ],
  • "sample_reference": "Sample 101",
  • "sample_date": "2019-02-25",
  • "custom_field_values": [
    ],
  • "test_results": [
    ],
  • "attachments": [],
  • "crop_store_lot": {
    },
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "stats": {
    }
}

List assessment reports with token

Get assessment reports which includes detailed data about an assessment and it's nested objects with token

path Parameters
token
required
string <uuid>

token

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

lot_id
integer >= 1
Example: lot_id=3

Filter by the store-lot ID

template_id
integer >= 1
Example: template_id=3

Filter by the template ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "template": {
    },
  • "crop_name": "string",
  • "owner_organisation_name": "string",
  • "field_name": "North field",
  • "variety_name": "Accord",
  • "suitability": [
    ],
  • "sample_reference": "Sample 101",
  • "sample_date": "2019-02-25",
  • "custom_field_values": [
    ],
  • "test_results": [
    ],
  • "attachments": [],
  • "crop_store_lot": {
    },
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "stats": {
    }
}

Get assessment

Get this assessment

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "template_id": 2,
  • "suitability": [
    ],
  • "sample_reference": "Sample 101",
  • "sample_date": "2019-02-25",
  • "custom_field_values": [
    ],
  • "test_results": [
    ],
  • "attachments": [],
  • "sub_samples": [
    ],
  • "plot_id": 1,
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update assessment

Update an existing assessment

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "template_id": 2,
  • "suitability": [
    ],
  • "sample_reference": "Sample 101",
  • "sample_date": "2019-02-25",
  • "custom_field_values": [
    ],
  • "test_results": [
    ],
  • "attachments": [],
  • "sub_samples": [
    ],
  • "plot_id": 1,
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete assessment

Delete an existing assessment

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

List sub-sample names

Returns a paginated list of subsample names with their owner organisations. Defaults to returning the list of subsamples owned by the requester's organisation, but can be used to return names for any connected organisation via the team_ids parameter.

query Parameters
string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

search
string
Example: search=my-plot

Text search

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List assessment templates

Returns a paginated list of assessment templates

query Parameters
string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

search
string
Example: search=my-plot

Text search

is_active
boolean
Default: true

Returns all templates by default - supply false for this to show inactive templates

include_archived
boolean
Default: false

Returns only the latest versions of templates by default - supply true for this to show all templates

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create assessment template

Create an assessment template or create a new version of an existing template if old_template_id is provided

Request Body schema: application/json
old_template_id
integer

should be provided in case of creating a new version of an existing template

name
required
string

Template name

team_id
required
integer (TeamId) >= 1

Team ID

crop_id
required
integer (GenusId) >= 1

Genus ID

genus_id
integer (GenusId) >= 1

Genus ID

description
string

Description

Array of objects

Custom fields for Template

required
Array of objects (AssessmentTemplateSection) non-empty

Responses

Request samples

Content type
application/json
{
  • "old_template_id": 0,
  • "name": "Potato main crop",
  • "team_id": 6,
  • "crop_id": 2,
  • "genus_id": 2,
  • "description": "Used in ARRA 51",
  • "custom_fields": [
    ],
  • "sections": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "old_template_id": 0,
  • "version": 0,
  • "name": "Potato main crop",
  • "team_id": 6,
  • "team_name": "Bobs Farm",
  • "crop_id": 2,
  • "genus_id": 2,
  • "genus_name": "string",
  • "specifications": "UK,ES",
  • "description": "Used in ARRA 51",
  • "custom_fields": [
    ],
  • "sections": [
    ],
  • "latest_id": 0,
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List template names

Returns a paginated list of assessment template id and names

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

search
string
Example: search=my-plot

Text search

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Get assessment template

Retrieves template and related objects

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "old_template_id": 0,
  • "version": 0,
  • "name": "Potato main crop",
  • "team_id": 6,
  • "team_name": "Bobs Farm",
  • "crop_id": 2,
  • "genus_id": 2,
  • "genus_name": "string",
  • "specifications": "UK,ES",
  • "description": "Used in ARRA 51",
  • "custom_fields": [
    ],
  • "sections": [
    ],
  • "latest_id": 0,
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Edit assessment template

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
old_template_id
integer

should be provided in case of creating a new version of an existing template

name
required
string

Template name

team_id
required
integer (TeamId) >= 1

Team ID

crop_id
required
integer (GenusId) >= 1

Genus ID

genus_id
integer (GenusId) >= 1

Genus ID

description
string

Description

Array of objects

Custom fields for Template

required
Array of objects (AssessmentTemplateSection) non-empty

Responses

Request samples

Content type
application/json
{
  • "old_template_id": 0,
  • "name": "Potato main crop",
  • "team_id": 6,
  • "crop_id": 2,
  • "genus_id": 2,
  • "description": "Used in ARRA 51",
  • "custom_fields": [
    ],
  • "sections": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "old_template_id": 0,
  • "version": 0,
  • "name": "Potato main crop",
  • "team_id": 6,
  • "team_name": "Bobs Farm",
  • "crop_id": 2,
  • "genus_id": 2,
  • "genus_name": "string",
  • "specifications": "UK,ES",
  • "description": "Used in ARRA 51",
  • "custom_fields": [
    ],
  • "sections": [
    ],
  • "latest_id": 0,
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List QC summaries

Returns a page of crop quality summaries. This is effectively the union of visible plots and store lots augmented with the their most recent quality assessment result, sorted by the most recent assessments first.

path Parameters
template_id
required
integer

Restrict to plots and lots which have assessments for this template

query Parameters
page_size
integer [ 1 .. 100 ]
Default: 20

Page size

source
string
Enum: "plot" "lot"

Filter to return only plots or lots (defaults to both combined)

sample_date_gte
string
Example: sample_date_gte=2021-01-01

Exclude assessments where the sample date is strictly less than this value

sample_date_lte
string
Example: sample_date_lte=2021-09-01

Exclude assessments where the sample date is strictly greater than this value

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

store_id
integer >= 1
Example: store_id=3

Filter by the store ID

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

lot_id
integer >= 1
Example: lot_id=3

Filter by the store-lot ID

specifications
string
Example: specifications=UK,ES

Comma separated list of quality specification names. Only include plots and plots where the most recent assessment passes any of the supplied specifications.

search
string
Example: search=north

Search for crop owner, field name, plot name or lot name

Responses

Response samples

Content type
No sample

Share crop quality assessments

Prepares a crop quality report for sharing. If a list of emails is provided then share the filtered set of quality assessments with each addressee. If an email list is not provided then simply return the url that would have been sent in the email. It is assumed that these users are not KisanHub users. Must specify either plot_id/plot_ids or lot_id/lot_ids

Request Body schema: application/json
plot_id
integer >= 1

Plot id to share assessments from

plot_ids
Array of integers[ items >= 1 ]

Plot ids to share assessments from

lot_id
integer

Lot id to share assessments from

lot_ids
Array of integers[ items >= 1 ]

Lot ids to share assessments from

template_id
required
integer

template id to share assessments from

emails
Array of strings non-empty [ items >= 4 characters ]

List of email addresses

Responses

Request samples

Content type
application/json
{
  • "plot_id": 20,
  • "plot_ids": [
    ],
  • "lot_id": 3,
  • "lot_ids": [
    ],
  • "template_id": 0,
  • "emails": [
    ]
}

Response samples

Content type
application/json
{
  • "url": "string"
}

List emails of shares

A truncated list of unique emails with which the requesting user has shared diaries or assessments

query Parameters
search
string
Example: search=my-plot

Text search

Responses

Response samples

Content type
application/json
[
  • "you@nowhere.com"
]

Crop monitoring

An crop monitoring diary is designed to capture all of the information recorded on a field visit. It groups multiple pieces of information so that they can be referenced to a certain field visit, and viewed in context of the other information collected. It may consist of a date, growth stages, notes, images and observations. Observations provide a structured and repeatable way of recording a regular or universal piece of information, like pest or disease presence or a crop milestone

List diaries

Returns a paginated list of crop monitoring diaries. Diaries can be associated with either a plot or a store lot.

Diary visibility is determined by the following rules:

  • It was created by my organisation
  • It was created by another organisation that is sharing diaries with me and I can see the associated lot or plot
  • It was created by the organisation that owns the associated plot or lot and I can see the plot or lot
  • The user is KisanHub staff

Note that all visible diaries are editable

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

date_gte
string <date>
Example: date_gte=2019-01-01

Lower threshold for the date when observation is captured

date_lte
string <date>
Example: date_lte=2019-01-01

Upper threshold for the date when observation is captured

user_id
integer (PrimaryKey) >= 1
Example: user_id=1

ID of the user who has reported the observation

critical
boolean
Deprecated

Whether to retrieve only critical observations

parameter_id
integer

Observation parameter ID

parameter_name
string

Name of the parameter to search by

risk_level
string
Enum: "low" "medium" "high"

Filter on risk level

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create diary

Create a new crop monitoring diary

Request Body schema: application/json
One of
Any of
lot_id
required
integer >= 1

Store lot ID

date
required
string <date>
location
Array of numbers or null <float> = 2 items

Point location as a [lng, lat] pair

notes
string
Array of objects (Attachments)
Array of objects (ObservationSample)
created_by_name
string

Full name of diary creator

Responses

Request samples

Content type
application/json
Example
{
  • "lot_id": 1,
  • "date": "2020-05-26",
  • "location": [
    ],
  • "notes": "string",
  • "uploaded_files": [],
  • "samples": [
    ],
  • "created_by_name": "Bob Smith"
}

Response samples

Content type
application/json
Example
{
  • "lot_id": 1,
  • "id": 1,
  • "field_id": 1,
  • "field_name": "string",
  • "farm_id": 1,
  • "farm_name": "string",
  • "team_id": 1,
  • "team_name": "string",
  • "organisation_id": 1,
  • "organisation_name": "string",
  • "genus_id": 0,
  • "genus_name": "potato",
  • "variety_id": 0,
  • "variety_name": "voyager",
  • "date": "2020-05-26",
  • "location": [
    ],
  • "access": "read-edit",
  • "notes": "string",
  • "uploaded_files": [],
  • "samples": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "created_by_name": "Bob Smith"
}

Retrieve diary

Retrieve a diary. Contains more detail then the list-observation endpoint

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
Example
{
  • "lot_id": 1,
  • "id": 1,
  • "field_id": 1,
  • "field_name": "string",
  • "farm_id": 1,
  • "farm_name": "string",
  • "team_id": 1,
  • "team_name": "string",
  • "organisation_id": 1,
  • "organisation_name": "string",
  • "genus_id": 0,
  • "genus_name": "potato",
  • "variety_id": 0,
  • "variety_name": "voyager",
  • "date": "2020-05-26",
  • "location": [
    ],
  • "access": "read-edit",
  • "notes": "string",
  • "uploaded_files": [],
  • "samples": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "created_by_name": "Bob Smith",
  • "plot_bounds": [
    ]
}

Update diary

Edit a diary

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

query Parameters
notify
string
Deprecated

Notify the owner of the plot about changes made. Deprecated if favour of a more user-driven notification scheme.

Request Body schema: application/json
One of
Any of
lot_id
required
integer >= 1

Store lot ID

date
required
string <date>
location
Array of numbers or null <float> = 2 items

Point location as a [lng, lat] pair

notes
string
Array of objects (Attachments)
Array of objects (ObservationSample)
created_by_name
string

Full name of diary creator

Responses

Request samples

Content type
application/json
Example
{
  • "lot_id": 1,
  • "date": "2020-05-26",
  • "location": [
    ],
  • "notes": "string",
  • "uploaded_files": [],
  • "samples": [
    ],
  • "created_by_name": "Bob Smith"
}

Response samples

Content type
application/json
{
  • "name": [
    ]
}

Delete a diary

Delete a diary

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Monitoring diary report Deprecated

DEPRECATED: use the standard list-observations API in preference.

Summarised list of crop monitoring diaries sorted by reverse date order. Diaries may be associated with either plots or store lots.

A user has read-write access to a field-sourced diary if any of the following conditions are met:

  • they are in the same team as the farmer (i.e team of the parent farm)
  • the diary was created by someone in their team
  • the diary was created by the farmer and they have edit access to the Plot
  • the diary was created by someone other than the farmer, the plot has been shared as read/write with their team, and the organisation that created the diary has set the "is_sharing_diaries" flag for the user's organisation
  • they are Kisanhub staff members

A user has read-only access to a diary if none of the previous conditions were met but the plot has been shared with their team as read-only and any of the following conditions are met:

  • the diary was created by the farmer
  • the diary was not created by the farmer, but the organisation that created the diary has set the "is_sharing_diaries" flag for the user's organisation

The access rules for store lots are the same but apply to the plot associated with the store lot.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

format
string
Default: "json"
Enum: "csv" "json"
Example: format=csv

Change the output format. Defaults to JSON

source
string
Enum: "field" "store"

Set to "field" to restrict to field diaries (i.e from a plot), or "store" to restrict to store diaries (i.e from a store lot). If not specified returns both field and store monitoring diaries

date_gte
string <date>
Example: date_gte=2019-01-01

Lower threshold for the date when observation is captured

date_lte
string <date>
Example: date_lte=2019-01-01

Upper threshold for the date when observation is captured

user_id
integer (PrimaryKey) >= 1
Example: user_id=1

ID of the user who has reported the observation

critical
boolean
Deprecated

Whether to retrieve only critical observations

parameter_id
integer

Observation parameter ID

parameter_name
string

Name of the parameter to search by

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

store_id
integer >= 1
Example: store_id=3

Filter by the store ID

lot_id
integer >= 1
Example: lot_id=3

Filter by the store-lot ID

crop_id
integer (PrimaryKey) >= 1
Deprecated
Example: crop_id=1

ID of the crop. Deprecated - please use genus_id

Responses

Response samples

Content type
{
  • "total": 0,
  • "results": [
    ]
}

Get monitoring report

Returns a detailed report for a particular observation

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Id of the observation

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "date": "2019-01-01",
  • "reporter": {
    },
  • "team": {
    },
  • "farm": {
    },
  • "field": {
    },
  • "crop": {
    },
  • "variety": {
    },
  • "critical": true,
  • "notes": "string",
  • "plot": {
    },
  • "location": [
    ],
  • "primary_growth_stage": {
    },
  • "secondary_growth_stage": {
    },
  • "percent_field_cover": 0,
  • "samples": [
    ],
  • "uploaded_files": [],
  • "attachments": [
    ]
}

Share crop monitoring diaries

Share one or more crop monitoring diaries. In case that one or more email addresses are provided, it going to send an email. It is assumed that these users are not KisanHub users

Request Body schema: application/json
diary_ids
required
Array of integers non-empty

List of crop monitoring diary IDs

emails
Array of strings[ items >= 4 characters ]

List of email addresses

Responses

Request samples

Content type
application/json
{
  • "diary_ids": [
    ],
  • "emails": [
    ]
}

Response samples

Content type
application/json
{
  • "url": "string"
}

List emails of shares Deprecated

A truncated list of unique emails with which the requesting user has shared diaries

query Parameters
search
string
Example: search=my-plot

Text search

Responses

Response samples

Content type
application/json
[
  • "you@nowhere.com"
]

Shared monitoring diary report

Return all shared crop monitoring diaries using the tokenised url that is sent in the share email generated by the share diaries API

path Parameters
token
required
string

Share token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Shared diary report (legacy) Deprecated

DEPRECATED: use newer v2 API

path Parameters
token
required
string

Share token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List observation parameters

Return the list of observation parameters for crops

query Parameters
string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

crop_ids
integer
Example: crop_ids=2,3

Comma seperated string of crop ids

category
string

Observation category name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List observation parameter summaries

Return a paginated and summarised list of observation parameters

query Parameters
string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

search
string
Example: search=my-plot

Text search

crop_ids
integer
Example: crop_ids=2,3

Comma seperated string of crop ids

category
string

Observation category name

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

List observation parameters - admin

Admin staff-only endpoint that lists all parameters with their translations

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "category_id": 1,
  • "genus_ids": [
    ],
  • "minimum_sample_count": 1,
  • "format": "date",
  • "unit_type": "g",
  • "type": "DATE_VARIABLE_TYPE",
  • "category": {
    },
  • "name": {
    }
}

Create observation parameter

Create an observation parameter with name translations. Only available to KisanHub staff

Request Body schema: application/json
id
string

Id of the observation parameter

category_id
required
integer >= 1

Category ID

genus_ids
Array of integers[ items >= 1 ]

List of applicable genus ids

minimum_sample_count
required
integer
Default: 1

Minimum number of samples that should be taken of this type

format
required
string (ParameterFormat)
Enum: "date" "float" "count" "percentage" "length" "weight" "risk_level"

Value format.

The following validation is performed for each type:

Value Validation
date UTC datetime
float Any floating point
count Integer >= 0
percentage Float between 0 and 100
length Positive floating point
weight Positive floating point
risk_level Integer between 1 and 10
unit_type
string
Enum: "g" "kg" "mm" "cm" "m" "t" "t/ha"

Unit for length/weight formats

type
string
Deprecated
Enum: "DATE_VARIABLE_TYPE" "FLOAT_VARIABLE_TYPE"

Legacy type - use format instead

required
object (Translations)

Translations for a single text string

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "category_id": 1,
  • "genus_ids": [
    ],
  • "minimum_sample_count": 1,
  • "format": "date",
  • "unit_type": "g",
  • "type": "DATE_VARIABLE_TYPE",
  • "name": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "category_id": 1,
  • "genus_ids": [
    ],
  • "minimum_sample_count": 1,
  • "format": "date",
  • "unit_type": "g",
  • "type": "DATE_VARIABLE_TYPE",
  • "category": {
    },
  • "name": {
    }
}

List observation categories

Return the list of observation categories. The names are translated to the requested language

query Parameters
string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List observation categories - admin

Admin staff-only endpoint that lists all categories with their translations

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "description": "string",
  • "applies_to": "field",
  • "name": {
    }
}

Create observation category

Create an observation category. Only available to KisanHub staff

Request Body schema: application/json
description
string

Description

applies_to
string
Enum: "field" "store"

Determine whether this category is only applicable to a particular source

required
object (Translations)

Translations for a single text string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "applies_to": "field",
  • "name": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "description": "string",
  • "applies_to": "field",
  • "name": {
    }
}

List emails of shares

A truncated list of unique emails with which the requesting user has shared diaries or assessments

query Parameters
search
string
Example: search=my-plot

Text search

Responses

Response samples

Content type
application/json
[
  • "you@nowhere.com"
]

Crop tags

Crop tags allow users to group plots by common tags, to allow for customizable filtering of plots. These are organized by categories, and subsequently by tags within a category. Categories within an organsation must be unique, and tags within a category must be unique. Categories and tags do not support upper case letters, only lower case letters are permitted.

Creates a crop tag category

Creates a crop tag category - a collection of crop tags

Request Body schema: application/json
label
string

The label representing this category

Responses

Request samples

Content type
application/json
{
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "organisation_id": 1,
  • "id": 1,
  • "label": "string"
}

List crop tag categories

List the crop tag categories within the user's organisation

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer >= 0
Default: 0

Allow unbounded pages by default

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

Get crop tag category

Return a crop tag category by id

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "organisation_id": 1,
  • "id": 1,
  • "label": "string"
}

Creates a crop tag

Creates a crop tag, which sit inside a crop tag category

Request Body schema: application/json
category_id
required
integer >= 1

ID of the category this crop tag category belongs to.

label
required
string

The tag's label

Responses

Request samples

Content type
application/json
{
  • "category_id": 1,
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "organisation_id": 1,
  • "organisation_name": "my organisation",
  • "category_label": "string",
  • "category_id": 1,
  • "label": "string"
}

List crop tags

List the crop tags a user can see - this is the user's organisations tags and those of organisations which have shared a plot with the users organisation

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

page_size
integer >= 0
Default: 0

Allow unbounded pages by default

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

organisation_ids
integer
Example: organisation_ids=1,2,3

Comma-separated list of organisation IDs.

category_id
integer >= 1
Example: category_id=1

Filter by the category ID

plot_id
integer >= 1
Example: plot_id=3

Return the set of tags that it is possible to assign to the plot with this ID

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

Get crop tag

Return a crop tag by id

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "organisation_id": 1,
  • "organisation_name": "my organisation",
  • "category_label": "string",
  • "category_id": 1,
  • "label": "string"
}

Activity feed

The activity feed represents a stream of activities relevant to interested parties, and is used to give an overview of farming activies and notes within a given timeframe. The feed is presented in reverse chronological order.

Get activity-feed events

List events with regards to farming practices. 'Events' are any type of activity relevant to a crop or with regards to a given trade. Examples include a monitoring diary of a crop, an operation carried out on that crop, or a record of a trade involving the crop. The feed is listed in reverse chronologial order. The amount of results in a response from this endpoint will vary, as it will return at a minimum the number of objects set by the minimum_page_size parameter. If more events have taken place on the same day as the last events within this query, all events from that day will be returned.

query Parameters
plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

search
string
Example: search=my-plot

Text search for any of plot, field, farm, organisation, crop or variety

minimum_page_size
integer <= 20
Default: 10

Minimum number of results to return from the API. More results can be returned, as the API will include all results from the last day where results exist

from_date
string <date>
Example: from_date=2020-01-02T10:00:00Z

From date

to_date
string <date>
Example: to_date=2020-01-23T15:00:00Z

To date

event_types
string
Enum: "monitoring_diary" "sowing_operation" "harvest_operation" "fertiliser_operation" "intercultural_operation" "land_preparation_operation" "pesticide_operation" "irrigation_operation" "trading_agreement" "certificate" "plot_state"
Example: event_types=pesticide_operation,fertiliser_operation

Comma separated list of types of activities to filter for

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

Store

A store is place to keep farm produce. Different type of stores can be created for different crops. Each store consists of multiple sections called store lots in which different crops or crops with different varieties can be stored.

List stores

Return a paginated list of stores. The stores are visible to a user if any of the following conditions are met:

  • The calling user is in the same organisation which owns the stores
  • The store owned by a organisation which is connected to the calling user's organisation
  • The user can see any store lots are currently, or have been in the past, contained within the store
  • The user is a staff user
query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

search
string

Return stores that include this string in store name

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create store

Create a new store. Staff users can create a store for any team, regular users can create stores for their own team and SITE & REG admins can create stores for any team under the same site.

Request Body schema: application/json
name
required
string

Name of the crop store

store_type
required
string
Enum: "ambient" "cold" "farm" "grain"

Type of the store

storage_type
string
Enum: "box" "bulk"

produce storage type

address
required
string

Full text address of the store

location
required
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

team_id
required
integer >= 1

Team ID that owns the store

capacity_value
integer

Store capacity in the specified unit

capacity_unit
string
Default: "tonnes"
Enum: "tonnes" "bushels" "kilograms" "boxes"

Store capacity unit

Array of objects (Attachments)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "store_type": "ambient",
  • "storage_type": "box",
  • "address": "string",
  • "location": [
    ],
  • "team_id": 1,
  • "capacity_value": 0,
  • "capacity_unit": "tonnes",
  • "attachments": []
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "access": "read-edit",
  • "store_type": "ambient",
  • "storage_type": "box",
  • "address": "string",
  • "location": [
    ],
  • "team_id": 1,
  • "capacity_value": 0,
  • "capacity_unit": "tonnes",
  • "attachments": [],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Get store

Get a single store. The store is visible to a user if any of the following conditions are met:

  • The calling user is in the same team which owns the stores
  • The team that owns the store is a secondary team of a calling user
  • The user is a staff user
path Parameters
id
required
integer

Store ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "access": "read-edit",
  • "store_type": "ambient",
  • "storage_type": "box",
  • "address": "string",
  • "location": [
    ],
  • "team_id": 1,
  • "capacity_value": 0,
  • "capacity_unit": "tonnes",
  • "attachments": [],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Update store

Update a store. Staff users can update a store for any team, regular users can update stores for their own team and SITE & REG admins can update stores for any team under the same site.

path Parameters
id
required
integer

Store ID

Request Body schema: application/json
name
required
string

Name of the crop store

store_type
required
string
Enum: "ambient" "cold" "farm" "grain"

Type of the store

storage_type
string
Enum: "box" "bulk"

produce storage type

address
required
string

Full text address of the store

location
required
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

team_id
required
integer >= 1

Team ID that owns the store

capacity_value
integer

Store capacity in the specified unit

capacity_unit
string
Default: "tonnes"
Enum: "tonnes" "bushels" "kilograms" "boxes"

Store capacity unit

Array of objects (Attachments)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "store_type": "ambient",
  • "storage_type": "box",
  • "address": "string",
  • "location": [
    ],
  • "team_id": 1,
  • "capacity_value": 0,
  • "capacity_unit": "tonnes",
  • "attachments": []
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "access": "read-edit",
  • "store_type": "ambient",
  • "storage_type": "box",
  • "address": "string",
  • "location": [
    ],
  • "team_id": 1,
  • "capacity_value": 0,
  • "capacity_unit": "tonnes",
  • "attachments": [],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Get store permission

Returns the permission level for this store. A user has read/write access to a store if any of the following conditions are met:

  • They are in the same organisation as the organisation that owns the store
  • The user is KisanHub staff

Stores may be deleted if the user has r/w access and the store contains no lots. If the store does contain lots then noDeleteMessage will describe why delete isn't allowed.

Users that do not satify either of the above conditions may still see a store if their organisation is directly connected to the owner organisation, or if they can already see lots that are currently, or have been in the past, contained within the store

Returns 404 if the user has no access at all

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "access": "read-edit",
  • "noDeleteReason": "string"
}

GeoJSON stores

Store summaries in GeoJSON format. The same visibility rules as list-stores apply.

query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

season
string
Deprecated
Example: season=2019/20

Growing season

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Store lot

A store consists of a number of store-lots. Each store lot contains a single crop, either from a plot of from off-platform.

Create store lot

Create a new store lot. The set of required fields will differ depending on whether the lot is created for an on or off-platform plot.

If crop_store_id is supplied, then tonnage_in and loss_rate are both required.

If new_field_name is supplied then we will attempt to create a new off-platform field and plot with this name.

In this case the following fields are all required:

  • EITHER grower_team_id or grower_org_id
  • country
  • county
  • harvest_date
  • variety_id
Request Body schema: application/json
name
string

Lot name

tonnage_in
number <float> >= 0

Gross tonnage

loss_rate
number <float> [ 0 .. 100 ]

Expected loss percentage

adjustment
number

Manual adjustment in tonnes.

closed
boolean

If the lot is closed.

new_field_name
string

If specified then create an off-platform crop with a plot and field with this name

county
string

District/County: required only when created off-platform lots

country
string (CountryCode) = 2 characters

ISO 3166-1 country code

harvest_date
string <date>

The harvest date of the produce: required only when created off-platform lots

recommended_movement_date
string <date> (RecommendedMovementDate)

Recommended movement date. This can be set directly or via a store monitoring diary

plot_id
integer (PlotId) >= 1

Plot ID

crop_store_id
integer (StoreId) >= 1

Store ID

supplier_team_id
integer (TeamId) >= 1

Team ID

grower_team_id
integer (TeamId) >= 1

Team ID

grower_org_id
integer (GrowerOrgId) >= 1

Grower of the produce's organisation ID.

genus_id
integer (GenusId) >= 1

Genus ID

variety_id
integer (VarietyId) >= 1

Variety ID

tag_ids
Array of integers (TagIds)

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "name": "20-2009",
  • "tonnage_in": 0.1,
  • "loss_rate": 100,
  • "adjustment": 0,
  • "closed": true,
  • "new_field_name": "string",
  • "county": "string",
  • "country": "st",
  • "harvest_date": "2019-08-24",
  • "recommended_movement_date": "2019-08-24",
  • "plot_id": 4,
  • "crop_store_id": 1,
  • "supplier_team_id": 6,
  • "grower_team_id": 6,
  • "grower_org_id": 1,
  • "genus_id": 2,
  • "variety_id": 43,
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "20-2009",
  • "tonnage_in": 0.1,
  • "loss_rate": 100,
  • "adjustment": 0,
  • "closed": true,
  • "county": "string",
  • "country": "st",
  • "harvest_date": "2019-08-24",
  • "recommended_movement_date": "2019-08-24",
  • "available_tonnage": 0,
  • "tonnage_out": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "plot_id": 4,
  • "crop_store_id": 1,
  • "supplier_team_id": 6,
  • "grower_team_id": 6,
  • "grower_org_id": 1,
  • "genus_id": 2,
  • "variety_id": 43,
  • "tag_ids": [
    ]
}

List store lots

Return a paginated list of visible store lots. The following rules determine whether a lot is visible:

  • The lot was created by the user's team
  • The associated grower_team_id or supplier_team_id matches the users' team id
  • The user can see the plot associated with the lot
  • The lot is associated with a existing trade record that is visible to the user
  • the user has the legacy SITE_ADMIN permission and their team is in the Site of the team that created the lot
  • The user is KisanHub staff
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

team_ids
integer
Example: team_ids=1,2,3

Return the store lots associated with plots owned by these teams - matches either grower or supplier team

tag_id
integer >= 1

Filter by crop tag ID. Include objects that have been tagged with this tag.

tag_ids
Array of integers
Example: tag_ids=2,3

Comma-separated list of crop tag IDs. Includes objects that have been tagged with any of these tags

grower_ids
Array of integers[ items non-empty ]

Return the store lots associated with plots owned by these teams. It will be serialized as comma separated ids.

supplier_ids
Array of integers[ items non-empty ]

Return the store lots which has grower as these teams. It will be serialized as comma separated ids.

grower_organisation_ids
Array of integers[ items non-empty ]

Return the store lots associated with plots owned by these organisations. It will be serialized as comma separated ids.

supplier_organisation_ids
Array of integers[ items non-empty ]

Return the store lots which has grower as these organisations. It will be serialized as comma separated ids.

store_ids
Array of integers

Return the store lots which has supplier as these teams. It will be serialized as comma separated ids.

field_ids
Array of integers
Deprecated

Return the store lots associated with plots owned by these fields. It will be serialized as comma separated ids.

group_id
integer >= 1
Example: group_id=43

Filter by the organisation group ID

field_name
string

Return the store lots associated with these fields.

genus_ids
Array of integers

Return the store lots having these crops. It will be serialized as comma separated ids.

variety_ids
Array of integers

Return the store lots having these varieties. It will be serialized as comma separated ids.

off_platform
string
Enum: "only" "exclude"

If only then only returns lots for "off-platform" plots· If exclude then exclude lots for "off-platform" plots. If not specified then all lots are returned.

closed
boolean

Return the store lots based on the “closed“ status of the store lot. open or close or all of them(if not given).

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

harvest_from
string <date>
Example: harvest_from=2020-01-01

Filter store-lot by harvest after a given date

harvest_to
string <date>
Example: harvest_to=2020-01-02

Filter store-lot by harvest up to a given date

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

List store lot report

Return a paginated list of all store lots with foreign keys expanded i.e report that are either created by user's team or user's team is grower_team or supplier_team of the lot.

query Parameters
search
string

Return store lots that include this string in the name

page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

team_ids
integer
Example: team_ids=1,2,3

Return the store lots associated with plots owned by these teams - matches either grower or supplier team

tag_id
integer >= 1

Filter by crop tag ID. Include objects that have been tagged with this tag.

tag_ids
Array of integers
Example: tag_ids=2,3

Comma-separated list of crop tag IDs. Includes objects that have been tagged with any of these tags

grower_ids
Array of integers[ items non-empty ]

Return the store lots associated with plots owned by these teams. It will be serialized as comma separated ids.

supplier_ids
Array of integers[ items non-empty ]

Return the store lots which has grower as these teams. It will be serialized as comma separated ids.

grower_organisation_ids
Array of integers[ items non-empty ]

Return the store lots associated with plots owned by these organisations. It will be serialized as comma separated ids.

supplier_organisation_ids
Array of integers[ items non-empty ]

Return the store lots which has grower as these organisations. It will be serialized as comma separated ids.

store_ids
Array of integers

Return the store lots which has supplier as these teams. It will be serialized as comma separated ids.

field_ids
Array of integers
Deprecated

Return the store lots associated with plots owned by these fields. It will be serialized as comma separated ids.

group_id
integer >= 1
Example: group_id=43

Filter by the organisation group ID

field_name
string

Return the store lots associated with these fields.

genus_ids
Array of integers

Return the store lots having these crops. It will be serialized as comma separated ids.

variety_ids
Array of integers

Return the store lots having these varieties. It will be serialized as comma separated ids.

off_platform
string
Enum: "only" "exclude"

If only then only returns lots for "off-platform" plots· If exclude then exclude lots for "off-platform" plots. If not specified then all lots are returned.

closed
boolean

Return the store lots based on the “closed“ status of the store lot. open or close or all of them(if not given).

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

format
string
Default: "json"
Enum: "csv" "json"
Example: format=csv

Change the output format. Defaults to JSON

harvest_from
string <date>
Example: harvest_from=2020-01-01

Filter store-lot by harvest after a given date

harvest_to
string <date>
Example: harvest_to=2020-01-02

Filter store-lot by harvest up to a given date

recommended_movement_date_from
string <date>
Example: recommended_movement_date_from=2022-01-02

Filter lots that have a recommended_movement_date on or after this date

recommended_movement_date_to
string <date>
Example: recommended_movement_date_to=2022-02-05

Filter lots that have a recommended_movement_date on or before this date

Responses

Response samples

Content type
application/json
{
  • "total_tonnage": 0,
  • "total": 0,
  • "results": [
    ]
}

Retrieve store lot

Get a new store lot.

path Parameters
id
required
integer

Store lot id

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "20-2009",
  • "tonnage_in": 0.1,
  • "loss_rate": 100,
  • "adjustment": 0,
  • "closed": true,
  • "county": "string",
  • "country": "st",
  • "harvest_date": "2019-08-24",
  • "recommended_movement_date": "2019-08-24",
  • "available_tonnage": 0,
  • "tonnage_out": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "plot_id": 4,
  • "crop_store_id": 1,
  • "supplier_team_id": 6,
  • "grower_team_id": 6,
  • "grower_org_id": 1,
  • "genus_id": 2,
  • "variety_id": 43,
  • "tag_ids": [
    ]
}

List crop tags for a lot

List of crop tags on a lot

path Parameters
id
required
integer

Store lot id

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

Add a crop tag to a lot

Add a tag to a lot

path Parameters
id
required
integer

Store lot id

Request Body schema: application/json
tag_id
integer >= 1

ID of the crop tag added to this lot

Responses

Request samples

Content type
application/json
{
  • "tag_id": 1
}

Response samples

Content type
application/json
{
  • "tag_id": "string",
  • "lot_id": 1
}

Remove a crop tag from a lot

path Parameters
id
required
integer

Store lot id

tag_id
required
integer >= 1

Crop tag ID.

Responses

Get store lot report

Get a store lot report by id

path Parameters
id
required
integer

Store lot id

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "20-2009",
  • "tonnage_in": 0.1,
  • "loss_rate": 100,
  • "adjustment": 0,
  • "closed": true,
  • "county": "string",
  • "country": "st",
  • "harvest_date": "2019-08-24",
  • "recommended_movement_date": "2019-08-24",
  • "available_tonnage": 0,
  • "tonnage_out": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "assessment_count": 0,
  • "is_off_platform": true,
  • "plot": {
    },
  • "store": {
    },
  • "supplier_team": {
    },
  • "grower_team": {
    },
  • "grower_organisation_id": 0,
  • "genus": {
    },
  • "variety": {
    },
  • "tags": [
    ],
  • "field": {
    },
  • "actual_harvest_date": "2019-08-24",
  • "team": {
    },
  • "crop": {
    },
  • "diary_count": 0
}

Partially update a Lot

Partial update to a store lot. Enables adjustments to loss rate, wastage, closing a lot and adding a comment. Keys should not be sent for values that have not changed.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
loss_rate
number
adjustment
number
is_closed
boolean
tag_ids
Array of integers (TagIds)

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "loss_rate": 0,
  • "adjustment": 0,
  • "is_closed": true,
  • "tag_ids": [
    ]
}

Add comment to a Lot

Add a comment to a store lot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
comment
string

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

List store lot quality metrics Deprecated

Deprecated endpoint related to the legacy Labs module Return an unpaginated list of quality report metrics for the specified store lot

path Parameters
id
required
integer

Store lot id

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

list store lot events

Return a paginated list of lot events reverse ordered by date created. A user can view a CropStoreLot if it is shared with them or their team, or it is owned by their team.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Trade record

A document that relates a load moved, or to be moved, from Source to Destination to fulfill a specific trade. Trade records are subject to certain restrictions on who can edit certain document fields. All of pay_weight, sales_weight, defects and grower_payment_amount are termed 'outcomes'. Outcomes are only editable by the buying organisation, and only buying organisations can mark tickets as completed. In summary:

  1. Only buyers can create already completed tickets
  2. Buyers can update any field regardless of trade record state
  3. Suppliers can create a non-completed ticket, but can’t create outcomes on ticket creation
  4. Suppliers can edit non outcome fields at any point on any non-completed trade record

List trade records

Return a paginated list of trade records, in reverse chronological order. A user may see records if any of these conditions are met:

  • They are the supplier organisation
  • They are the recipient organisation
  • They are marked as an "additional_party" in the associated trading agreement
  • They originally created the trade record
query Parameters
string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create a trade record

Creates a trade record validating against just mandatory fields and without validating against it’s passport template. In the instance where grower_org_id is missing, it will default to use supplier_org_id.

Full validation against all fields required by the template will be performed in the send-trade-record endpoint.

A trade record must either refer to an existing plot or store lot. However you can create an "off-platform" crop by providing a new_field_name (for an off-platform field), and/or a new_lot_name (for an off-platform store lot). When creating an off-platform field the caller must create an off-platform lot: however an on-platform field may be paired with an off-platform lot. Off-platform fields must specify both region and country of origin.

Request Body schema: application/json
Any of
general_tuber_count_10kg
integer [ 0 .. 1000 ]

Tuber count

general_dry_matter
integer [ 0 .. 100 ]

The expected or actual dry matter percentage

general_sprouts_stolons
integer [ 0 .. 100 ]

The % of this load that contains/may contain sprouts

general_starch_content
integer [ 0 .. 100 ]

The expected or actual starch content expressed as a percentage

color_defects_green
integer [ 0 .. 100 ]

The % of this load that have green color defect

color_defects_purple
integer [ 0 .. 100 ]

The % of this load that have purple color defect

external_rots_breakdown
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_slug_worm
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

chipping_fry_colour
integer [ 1 .. 7 ]

Fry color indication on a scale from 1 to 7, where 1= very light, 7 = dark

chipping_colour_consistency
number <= 1

Chipping color consistency

chipping_internal_discoloration
integer [ 1 .. 9 ]

Internal discoloration on a scale from 1 to 9

chipping_glucose_percent
integer [ 0 .. 100 ]

The expected glucose level

supplier_org_id
required
integer >= 1

Seller ID

recipient_org_id
required
integer >= 1

Buyer ID

trading_agreement_id
required
integer >= 1

Trading agreement

lot_id
integer >= 1

The store lot reference from where produce is being supplied

plot_id
integer >= 1

The plot reference from where produce is being supplied

template_id
required
integer >= 1

The passport template that will be used to validate trade record

grower_org_id
integer (GrowerOrgId) >= 1

Grower of the produce's organisation ID.

new_field_name
string (NewFieldName)

Create a new off-platform field with this name. The region, country and variety_id properties will also be required

variety_id
integer (VarietyId) >= 1

Variety ID

region
string (OffPlatformRegion)

Region/county of off-platform field

country_code
string (CountryCode) = 2 characters

ISO 3166-1 country code

new_lot_name
string

Create a new off-platform lot with this name. Both region and country are also required

date_of_harvest
required
string <date>

The date the crop was harvested, required when creating an off platform lot

washed
boolean

whether this crop is washed

defects
string

User comments about defects in the load.

general_stored_temperature
number <= 50

The actual stored temperature in degrees Celcius

general_foreign_matter
integer [ 0 .. 100 ]

The % of this load that contains/may contain foreign matter

color_defects_other_discolouration
integer [ 0 .. 100 ]

The % of this load that have other defective colors defect

external_scab_lt_5pct
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_pest_damage
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_disease_infection
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_irregular_shape
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_other
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_disease_infection
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_major_bruise_percent
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_minor_bruise_percent
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_other
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

Array of objects (ChemicalDeclarationAnswer)

Answers to all the chemical declarations, if chemical is applied or not?.

Array of objects or null (TradeRecordAttachmentWrite)

Associated documentation/images with the trade record

due_time_on_site
required
string <date-time>

The date & time by which the lorry is due to arrive to pick up the produce

status
string
Enum: "transit" "completed" "cancelled" "returned"

Status of load transaction. Only buyer organisations are allowed to change the status to completed

load_number
required
string

The reference for the load.

load_actual_arrival_time
string <date-time>

The actual date & time when the lorry actually arrived to pick up the produce

load_time_complete
string <date-time>

The date & time when the lorry is loaded

load_expected_delivery_time
string <date-time>

The expected date & time when the lorry is due to arrive at the destination to dropoff the produce

load_actual_delivery_time
string <date-time>

The actual date & time when the lorry arrived at the destination to dropoff the produce

load_qty
number <= 50

Amount of crop on a single load. The load ticket will allow for boxes of different sizes as well as bulk transport

pay_weight
number <= 50

Weight(in tons) to be paid to the grower. This field is only visible to the buyer

grower_payment_amount
number >= 0

Total invoice amount of the load. This field is only visible to the buyer

sales_weight
number <= 50

Weight(in tons) to be sold to the customer. This field is only visible to the buyer

load_vehicle_reg
string

The vehicle registration plate for the vehicle carrying this load

load_haulier
string

The name of the Haulage Company carrying this load

load_trailer_no
string

The reference for the specific trailer for this load

load_seal_no
string

The references for all seals on this load.

load_box_markings
string

The name of the owner of the boxes carrying the crop

origin
required
string

County & Country where crop was grown

comments
string

These are comments that will be visible to everyone in the distribution list who receives the load ticket.

notes
string

These are comments that will only be visible to the Grower and anyone they have shared their crop with.

Responses

Request samples

Content type
application/json
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org_id": 1,
  • "recipient_org_id": 1,
  • "trading_agreement_id": 1,
  • "lot_id": 1,
  • "plot_id": 1,
  • "template_id": 1,
  • "grower_org_id": 1,
  • "new_field_name": "string",
  • "variety_id": 43,
  • "region": "string",
  • "country_code": "st",
  • "new_lot_name": "string",
  • "date_of_harvest": "2019-08-24",
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "comments": "string",
  • "notes": "string"
}

Response samples

Content type
application/json
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org_id": 1,
  • "grower_org_id": 1,
  • "recipient_org_id": 1,
  • "trading_agreement_id": 1,
  • "genus_id": 0,
  • "variety_id": 1,
  • "lot_id": 1,
  • "plot_id": 1,
  • "field_id": 0,
  • "template_id": 1,
  • "is_sent": true,
  • "supplier_org_name": "string",
  • "recipient_org_name": "string",
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [],
  • "size_ranges": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "date_of_harvest": "2019-08-24",
  • "comments": "string",
  • "notes": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Get a trade record

Get a trade-record

path Parameters
id
required
integer >= 1

Trade record id

Responses

Response samples

Content type
application/json
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org_id": 1,
  • "grower_org_id": 1,
  • "recipient_org_id": 1,
  • "trading_agreement_id": 1,
  • "genus_id": 0,
  • "variety_id": 1,
  • "lot_id": 1,
  • "plot_id": 1,
  • "field_id": 0,
  • "template_id": 1,
  • "is_sent": true,
  • "supplier_org_name": "string",
  • "recipient_org_name": "string",
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [],
  • "size_ranges": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "date_of_harvest": "2019-08-24",
  • "comments": "string",
  • "notes": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Update trade record

Update a trade record. See create-trade-record for more details.

path Parameters
id
required
integer >= 1

Trade record id

Request Body schema: application/json
Any of
general_tuber_count_10kg
integer [ 0 .. 1000 ]

Tuber count

general_dry_matter
integer [ 0 .. 100 ]

The expected or actual dry matter percentage

general_sprouts_stolons
integer [ 0 .. 100 ]

The % of this load that contains/may contain sprouts

general_starch_content
integer [ 0 .. 100 ]

The expected or actual starch content expressed as a percentage

color_defects_green
integer [ 0 .. 100 ]

The % of this load that have green color defect

color_defects_purple
integer [ 0 .. 100 ]

The % of this load that have purple color defect

external_rots_breakdown
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_slug_worm
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

chipping_fry_colour
integer [ 1 .. 7 ]

Fry color indication on a scale from 1 to 7, where 1= very light, 7 = dark

chipping_colour_consistency
number <= 1

Chipping color consistency

chipping_internal_discoloration
integer [ 1 .. 9 ]

Internal discoloration on a scale from 1 to 9

chipping_glucose_percent
integer [ 0 .. 100 ]

The expected glucose level

supplier_org_id
required
integer >= 1

Seller ID

recipient_org_id
required
integer >= 1

Buyer ID

trading_agreement_id
required
integer >= 1

Trading agreement

lot_id
integer >= 1

The store lot reference from where produce is being supplied

plot_id
integer >= 1

The plot reference from where produce is being supplied

template_id
required
integer >= 1

The passport template that will be used to validate trade record

grower_org_id
integer (GrowerOrgId) >= 1

Grower of the produce's organisation ID.

new_field_name
string (NewFieldName)

Create a new off-platform field with this name. The region, country and variety_id properties will also be required

variety_id
integer (VarietyId) >= 1

Variety ID

region
string (OffPlatformRegion)

Region/county of off-platform field

country_code
string (CountryCode) = 2 characters

ISO 3166-1 country code

new_lot_name
string

Create a new off-platform lot with this name. Both region and country are also required

date_of_harvest
required
string <date>

The date the crop was harvested, required when creating an off platform lot

washed
boolean

whether this crop is washed

defects
string

User comments about defects in the load.

general_stored_temperature
number <= 50

The actual stored temperature in degrees Celcius

general_foreign_matter
integer [ 0 .. 100 ]

The % of this load that contains/may contain foreign matter

color_defects_other_discolouration
integer [ 0 .. 100 ]

The % of this load that have other defective colors defect

external_scab_lt_5pct
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_pest_damage
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_disease_infection
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_irregular_shape
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_other
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_disease_infection
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_major_bruise_percent
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_minor_bruise_percent
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_other
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

Array of objects (ChemicalDeclarationAnswer)

Answers to all the chemical declarations, if chemical is applied or not?.

Array of objects or null (TradeRecordAttachmentWrite)

Associated documentation/images with the trade record

due_time_on_site
required
string <date-time>

The date & time by which the lorry is due to arrive to pick up the produce

status
string
Enum: "transit" "completed" "cancelled" "returned"

Status of load transaction. Only buyer organisations are allowed to change the status to completed

load_number
required
string

The reference for the load.

load_actual_arrival_time
string <date-time>

The actual date & time when the lorry actually arrived to pick up the produce

load_time_complete
string <date-time>

The date & time when the lorry is loaded

load_expected_delivery_time
string <date-time>

The expected date & time when the lorry is due to arrive at the destination to dropoff the produce

load_actual_delivery_time
string <date-time>

The actual date & time when the lorry arrived at the destination to dropoff the produce

load_qty
number <= 50

Amount of crop on a single load. The load ticket will allow for boxes of different sizes as well as bulk transport

pay_weight
number <= 50

Weight(in tons) to be paid to the grower. This field is only visible to the buyer

grower_payment_amount
number >= 0

Total invoice amount of the load. This field is only visible to the buyer

sales_weight
number <= 50

Weight(in tons) to be sold to the customer. This field is only visible to the buyer

load_vehicle_reg
string

The vehicle registration plate for the vehicle carrying this load

load_haulier
string

The name of the Haulage Company carrying this load

load_trailer_no
string

The reference for the specific trailer for this load

load_seal_no
string

The references for all seals on this load.

load_box_markings
string

The name of the owner of the boxes carrying the crop

origin
required
string

County & Country where crop was grown

comments
string

These are comments that will be visible to everyone in the distribution list who receives the load ticket.

notes
string

These are comments that will only be visible to the Grower and anyone they have shared their crop with.

Responses

Request samples

Content type
application/json
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org_id": 1,
  • "recipient_org_id": 1,
  • "trading_agreement_id": 1,
  • "lot_id": 1,
  • "plot_id": 1,
  • "template_id": 1,
  • "grower_org_id": 1,
  • "new_field_name": "string",
  • "variety_id": 43,
  • "region": "string",
  • "country_code": "st",
  • "new_lot_name": "string",
  • "date_of_harvest": "2019-08-24",
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "comments": "string",
  • "notes": "string"
}

Response samples

Content type
application/json
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org_id": 1,
  • "grower_org_id": 1,
  • "recipient_org_id": 1,
  • "trading_agreement_id": 1,
  • "genus_id": 0,
  • "variety_id": 1,
  • "lot_id": 1,
  • "plot_id": 1,
  • "field_id": 0,
  • "template_id": 1,
  • "is_sent": true,
  • "supplier_org_name": "string",
  • "recipient_org_name": "string",
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [],
  • "size_ranges": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "date_of_harvest": "2019-08-24",
  • "comments": "string",
  • "notes": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Delete trade record

Delete a trade record. Note that if the trade record has already been used to adjust store inventory then this will not be reverted: adjustment must be made manually. There is no undo.

path Parameters
id
required
integer >= 1

Trade record id

Responses

Partially update a trade record

Partially update a trade record. Only those properties supplied will be updated. See create-trade-record for more details.

path Parameters
id
required
integer >= 1

Trade record id

Request Body schema: application/json
Any of
general_tuber_count_10kg
integer [ 0 .. 1000 ]

Tuber count

general_dry_matter
integer [ 0 .. 100 ]

The expected or actual dry matter percentage

general_sprouts_stolons
integer [ 0 .. 100 ]

The % of this load that contains/may contain sprouts

general_starch_content
integer [ 0 .. 100 ]

The expected or actual starch content expressed as a percentage

color_defects_green
integer [ 0 .. 100 ]

The % of this load that have green color defect

color_defects_purple
integer [ 0 .. 100 ]

The % of this load that have purple color defect

external_rots_breakdown
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_slug_worm
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

chipping_fry_colour
integer [ 1 .. 7 ]

Fry color indication on a scale from 1 to 7, where 1= very light, 7 = dark

chipping_colour_consistency
number <= 1

Chipping color consistency

chipping_internal_discoloration
integer [ 1 .. 9 ]

Internal discoloration on a scale from 1 to 9

chipping_glucose_percent
integer [ 0 .. 100 ]

The expected glucose level

supplier_org_id
required
integer >= 1

Seller ID

recipient_org_id
required
integer >= 1

Buyer ID

trading_agreement_id
required
integer >= 1

Trading agreement

lot_id
integer >= 1

The store lot reference from where produce is being supplied

plot_id
integer >= 1

The plot reference from where produce is being supplied

template_id
required
integer >= 1

The passport template that will be used to validate trade record

grower_org_id
integer (GrowerOrgId) >= 1

Grower of the produce's organisation ID.

new_field_name
string (NewFieldName)

Create a new off-platform field with this name. The region, country and variety_id properties will also be required

variety_id
integer (VarietyId) >= 1

Variety ID

region
string (OffPlatformRegion)

Region/county of off-platform field

country_code
string (CountryCode) = 2 characters

ISO 3166-1 country code

new_lot_name
string

Create a new off-platform lot with this name. Both region and country are also required

date_of_harvest
required
string <date>

The date the crop was harvested, required when creating an off platform lot

washed
boolean

whether this crop is washed

defects
string

User comments about defects in the load.

general_stored_temperature
number <= 50

The actual stored temperature in degrees Celcius

general_foreign_matter
integer [ 0 .. 100 ]

The % of this load that contains/may contain foreign matter

color_defects_other_discolouration
integer [ 0 .. 100 ]

The % of this load that have other defective colors defect

external_scab_lt_5pct
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_pest_damage
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_disease_infection
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_irregular_shape
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

external_other
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_disease_infection
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_major_bruise_percent
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_minor_bruise_percent
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

internal_other
integer [ 0 .. 100 ]

The estimated proportion of the load with this defect

Array of objects (ChemicalDeclarationAnswer)

Answers to all the chemical declarations, if chemical is applied or not?.

Array of objects or null (TradeRecordAttachmentWrite)

Associated documentation/images with the trade record

due_time_on_site
required
string <date-time>

The date & time by which the lorry is due to arrive to pick up the produce

status
string
Enum: "transit" "completed" "cancelled" "returned"

Status of load transaction. Only buyer organisations are allowed to change the status to completed

load_number
required
string

The reference for the load.

load_actual_arrival_time
string <date-time>

The actual date & time when the lorry actually arrived to pick up the produce

load_time_complete
string <date-time>

The date & time when the lorry is loaded

load_expected_delivery_time
string <date-time>

The expected date & time when the lorry is due to arrive at the destination to dropoff the produce

load_actual_delivery_time
string <date-time>

The actual date & time when the lorry arrived at the destination to dropoff the produce

load_qty
number <= 50

Amount of crop on a single load. The load ticket will allow for boxes of different sizes as well as bulk transport

pay_weight
number <= 50

Weight(in tons) to be paid to the grower. This field is only visible to the buyer

grower_payment_amount
number >= 0

Total invoice amount of the load. This field is only visible to the buyer

sales_weight
number <= 50

Weight(in tons) to be sold to the customer. This field is only visible to the buyer

load_vehicle_reg
string

The vehicle registration plate for the vehicle carrying this load

load_haulier
string

The name of the Haulage Company carrying this load

load_trailer_no
string

The reference for the specific trailer for this load

load_seal_no
string

The references for all seals on this load.

load_box_markings
string

The name of the owner of the boxes carrying the crop

origin
required
string

County & Country where crop was grown

comments
string

These are comments that will be visible to everyone in the distribution list who receives the load ticket.

notes
string

These are comments that will only be visible to the Grower and anyone they have shared their crop with.

Responses

Request samples

Content type
application/json
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org_id": 1,
  • "recipient_org_id": 1,
  • "trading_agreement_id": 1,
  • "lot_id": 1,
  • "plot_id": 1,
  • "template_id": 1,
  • "grower_org_id": 1,
  • "new_field_name": "string",
  • "variety_id": 43,
  • "region": "string",
  • "country_code": "st",
  • "new_lot_name": "string",
  • "date_of_harvest": "2019-08-24",
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "comments": "string",
  • "notes": "string"
}

Response samples

Content type
application/json
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org_id": 1,
  • "grower_org_id": 1,
  • "recipient_org_id": 1,
  • "trading_agreement_id": 1,
  • "genus_id": 0,
  • "variety_id": 1,
  • "lot_id": 1,
  • "plot_id": 1,
  • "field_id": 0,
  • "template_id": 1,
  • "is_sent": true,
  • "supplier_org_name": "string",
  • "recipient_org_name": "string",
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [],
  • "size_ranges": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "date_of_harvest": "2019-08-24",
  • "comments": "string",
  • "notes": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Send a trade record

Save a trade record and send it to the email addresses specified. The trade record must meet the requirements defined in its passport template.

path Parameters
id
required
integer >= 1

Trade record id

Responses

Response samples

Content type
application/json
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org_id": 1,
  • "grower_org_id": 1,
  • "recipient_org_id": 1,
  • "trading_agreement_id": 1,
  • "genus_id": 0,
  • "variety_id": 1,
  • "lot_id": 1,
  • "plot_id": 1,
  • "field_id": 0,
  • "template_id": 1,
  • "is_sent": true,
  • "supplier_org_name": "string",
  • "recipient_org_name": "string",
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [],
  • "size_ranges": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "date_of_harvest": "2019-08-24",
  • "comments": "string",
  • "notes": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

List trade records report

Returns a paginated list of trade records details sorted by latest load due time on site.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

plot_id
integer >= 1
Example: plot_id=3

Filter by the plot ID

lot_id
integer >= 1
Example: lot_id=3

Filter by the store-lot ID

store_id
integer >= 1
Example: store_id=3

Filter by the store ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

from_delivery_date
string <date>

ISO date format.

to_delivery_date
string <date>

ISO date format.

supplier_org_id
integer (PrimaryKey) >= 1
Example: supplier_org_id=1

Supplier Organisation

recipient_org_id
integer (PrimaryKey) >= 1
Example: recipient_org_id=1

Recipient Organisation

load_number
string

Return trade records that include this string in load number.

source
string
Enum: "field" "store"

Filter on whether the lot came directly from the field or from a store

field_id
integer

Only return tickets from this field

field_name
string

Name of field. Only return tickets from this field.

delivery_date
string <date>

Only return tickets that were delivered on this date (ISO date format)

format
string
Default: "json"
Enum: "json" "csv"

Determine which format to return: load tickets can be serialised as JSON or as CSV. When serialised as CSV only the names of the various entities will be returned i.e not the primary keys.

draft
boolean

draft status of the load ticket.

status
string

Status of load

search
string

Search load records for supplier/recipient addresses, phone numbers or load ticket numbers which match this string

Responses

Response samples

Content type
{
  • "total": 0,
  • "results": [
    ]
}

Get a trade record report

Get a trade-record report.

path Parameters
id
required
integer >= 1

Trade record id

query Parameters
format
string
Enum: "pdf" "html" "json"

Expected response format.

Responses

Response samples

Content type
Example
{
  • "general_tuber_count_10kg": 1000,
  • "general_dry_matter": 100,
  • "general_sprouts_stolons": 100,
  • "general_starch_content": 100,
  • "color_defects_green": 100,
  • "color_defects_purple": 100,
  • "external_rots_breakdown": 100,
  • "external_slug_worm": 100,
  • "chipping_fry_colour": 1,
  • "chipping_colour_consistency": 1,
  • "chipping_internal_discoloration": 1,
  • "chipping_glucose_percent": 100,
  • "supplier_org": {},
  • "supplier_group": "string",
  • "recipient_org": {},
  • "trading_agreement": {
    },
  • "variety": {
    },
  • "lot": {
    },
  • "plot": {
    },
  • "template": {
    },
  • "created_by": {
    },
  • "updated_by": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_sent": true,
  • "genus": {
    },
  • "field_name": "string",
  • "week": 0,
  • "washed": true,
  • "defects": "string",
  • "general_stored_temperature": 50,
  • "general_foreign_matter": 100,
  • "color_defects_other_discolouration": 100,
  • "external_scab_lt_5pct": 100,
  • "external_pest_damage": 100,
  • "external_disease_infection": 100,
  • "external_irregular_shape": 100,
  • "external_other": 100,
  • "internal_disease_infection": 100,
  • "internal_major_bruise_percent": 100,
  • "internal_minor_bruise_percent": 100,
  • "internal_other": 100,
  • "chemical_declaration_answers": [
    ],
  • "attachments": [],
  • "size_ranges": [
    ],
  • "due_time_on_site": "2019-08-24T14:15:22Z",
  • "status": "transit",
  • "load_number": "ABC123",
  • "load_actual_arrival_time": "2019-08-24T14:15:22Z",
  • "load_time_complete": "2019-08-24T14:15:22Z",
  • "load_expected_delivery_time": "2019-08-24T14:15:22Z",
  • "load_actual_delivery_time": "2019-08-24T14:15:22Z",
  • "load_qty": 50,
  • "pay_weight": 50,
  • "grower_payment_amount": 0,
  • "sales_weight": 50,
  • "load_vehicle_reg": "AC118182",
  • "load_haulier": "string",
  • "load_trailer_no": "string",
  • "load_seal_no": "string",
  • "load_box_markings": "string",
  • "origin": "string",
  • "date_of_harvest": "2019-08-24",
  • "comments": "string",
  • "notes": "string"
}

Trade Record status choices list.

Returns a list of Trade Record status choices. Status describes the status of the load ticket.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Verify a load number is available

Verify a future load number within a trade record is available to the buyer.

path Parameters
load_number
required
string
Example: 5041092

A string to reference the load.

buyer_org_id
required
integer (OrganisationId) >= 1
Example: 1

The ID of the buyer organisation.

query Parameters
exclude_trade_record_id
integer >= 1

Trade record to be excluded by ID.

Responses

Response samples

Content type
application/json
true

Passport template

Template for passport/load ticket between organisations.

List template summaries

Returns a paginated and summarised list of active passport templates

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer >= 0
Default: 0

Allow unbounded pages by default

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

search
string
Example: search=my-plot

Text search

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

source_organisation_id
integer >= 1

Source organisation against which templates are filtered.

target_organisation_id
integer >= 1

Target organisation against which templates are filtered.

exclude_archived
boolean

If true then exclude archived templates. Ignored if false

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

List passport templates

Return a paginated list of passport templates. Note that this will only return non-archived templates by default i.e templates where latest_id is null.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer >= 0
Default: 0

Allow unbounded pages by default

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

search
string
Example: search=my-plot

Text search

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

source_organisation_id
integer >= 1

Source organisation against which templates are filtered.

target_organisation_id
integer >= 1

Target organisation against which templates are filtered.

exclude_archived
boolean

If true then exclude archived templates. Ignored if false

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Save passport template

Create a template for the given target organisation, genus and organisation of the logged user.

Note that passport templates may only be created by users in an organisation which is a direct (i.e paying) customer of KisanHub.

We never update existing templates (hence the lack of a PUT method). If an update is required then pass in the ID of the previous version of this template using old_template_id

Request Body schema: application/json
old_template_id
integer

If updating an existing template then supply the ID of the previous version: this is null for new templates

name
required
string

Name of versioned template given by user.

genus_id
required
integer

Genus ID.

target_organisation_id
required
integer

Organisation ID.

declaration
string

User entered notes that represent attestations to be confirmed in any load ticket.

comments
string
Deprecated

Indicate changes included in a particular version of a template.

prefix
string

Prefix to be used on a load ticket number.

required
Array of objects (TemplateField)

fields present in a passport template.

Array of objects (ChemicalDeclaration)

list of question related to application of chemical on load.

size_ranges
string

json array of upper limits for size ranges, -1 means infinity

Responses

Request samples

Content type
application/json
{
  • "old_template_id": 0,
  • "name": "string",
  • "genus_id": 0,
  • "target_organisation_id": 0,
  • "declaration": "I agree to the terms of service.",
  • "comments": "Added a new required field.",
  • "prefix": "COL",
  • "fields": [
    ],
  • "chemical_declarations": [
    ],
  • "size_ranges": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "latest_id": 0,
  • "name": "string",
  • "version": 0,
  • "published_on": "2019-08-24T14:15:22Z",
  • "published_by_user_id": 0,
  • "genus_id": 0,
  • "genus_name": "string",
  • "organisation_id": 0,
  • "target_organisation_id": 0,
  • "declaration": "I agree to the terms of service.",
  • "comments": "Added a new required field.",
  • "prefix": "COL",
  • "fields": [
    ],
  • "chemical_declarations": [
    ],
  • "size_ranges": "string"
}

Retrieve passport template

Returns the template specified by the id. Note that this will return any template, including one that has been archived.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "latest_id": 0,
  • "name": "string",
  • "version": 0,
  • "published_on": "2019-08-24T14:15:22Z",
  • "published_by_user_id": 0,
  • "genus_id": 0,
  • "genus_name": "string",
  • "organisation_id": 0,
  • "target_organisation_id": 0,
  • "declaration": "I agree to the terms of service.",
  • "comments": "Added a new required field.",
  • "prefix": "COL",
  • "fields": [
    ],
  • "chemical_declarations": [
    ],
  • "size_ranges": "string"
}

Archive template

Archive an active (non-archived) template. Ignored for archived templates

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Publish the given template. Deprecated

  • DEPRECATED *: templates are now automatically "published" on save.

Publish the given template, making it available for load tickets creation.

Note that passport templates may only be published by users in an organisation which is a direct (i.e paying) customer of KisanHub

path Parameters
id
required
integer >= 1

Passport template ID

Request Body schema: application/json
comments
string

Comments about this template version, mainly to indicate changes included in it.

Responses

Request samples

Content type
application/json
{
  • "comments": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "latest_id": 0,
  • "name": "string",
  • "version": 0,
  • "published_on": "2019-08-24T14:15:22Z",
  • "published_by_user_id": 0,
  • "genus_id": 0,
  • "genus_name": "string",
  • "organisation_id": 0,
  • "target_organisation_id": 0,
  • "declaration": "I agree to the terms of service.",
  • "comments": "Added a new required field.",
  • "prefix": "COL",
  • "fields": [
    ],
  • "chemical_declarations": [
    ],
  • "size_ranges": "string"
}

Certificate

Create/update/retrieve certificates for user/organisations.

Certificate report API

Paginated list of all certificates with full details.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

owner_type
string
Enum: "user" "organisation"
Example: owner_type=organisation

Certificate owned by either user/organisation.

owner_id
integer >= 1
Example: owner_id=1

ID of the owner.

certificate_type_id
integer >= 1
Example: certificate_type_id=1

ID of the certificate type (Cert Type API).

format
string
Value: "pdf"

Expected response format. By default api returns JSON response but returns a PDF when provided this query param

Responses

Response samples

Content type
{
  • "owner": {
    },
  • "certificate_type": {
    },
  • "owner_type": "user",
  • "classification": "Cereals",
  • "issued_by": "string",
  • "reference": "RR123456",
  • "start_date": "2019-08-24",
  • "renewal_date": "2019-08-24",
  • "attachment": {},
  • "is_private": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    }
}

Certificate list API

Paginated list of all certificates.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

owner_type
string
Enum: "user" "organisation"
Example: owner_type=organisation

Certificate owned by either user/organisation.

owner_id
integer >= 1
Example: owner_id=1

ID of the owner.

certificate_type_id
integer >= 1
Example: certificate_type_id=1

ID of the certificate type (Cert Type API).

Responses

Response samples

Content type
application/json
{
  • "owner_id": 1,
  • "certificate_type_id": 1,
  • "owner_type": "user",
  • "classification": "Cereals",
  • "issued_by": "string",
  • "reference": "RR123456",
  • "start_date": "2019-08-24",
  • "renewal_date": "2019-08-24",
  • "attachment": {},
  • "is_private": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Create certificate.

Creates a certificate for user/organisation.

Request Body schema: application/json
owner_id
required
integer >= 1

Owner ID either of user or organisation.

certificate_type_id
required
integer >= 1

Certificate type ID (Cert Type API).

classification
string

Scope/classification of this certificate.

issued_by
string

Issuer institute/org. of the certificate.

reference
required
string

Reference number given to the certificate.

start_date
required
string <date>

Start date of validation of the certificate.

renewal_date
required
string <date>

Renewal date of validation of the certificate.

object (Attachment)

File upload object with file_name and url of attachment.

is_private
required
boolean

If the certificate is private or public.

Responses

Request samples

Content type
application/json
{
  • "owner_id": 1,
  • "certificate_type_id": 1,
  • "classification": "Cereals",
  • "issued_by": "string",
  • "reference": "RR123456",
  • "start_date": "2019-08-24",
  • "renewal_date": "2019-08-24",
  • "attachment": {},
  • "is_private": true
}

Response samples

Content type
application/json
{
  • "owner_id": 1,
  • "certificate_type_id": 1,
  • "owner_type": "user",
  • "classification": "Cereals",
  • "issued_by": "string",
  • "reference": "RR123456",
  • "start_date": "2019-08-24",
  • "renewal_date": "2019-08-24",
  • "attachment": {},
  • "is_private": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Retrieve API for certificate.

Gets a certificate for user/organisation.

path Parameters
id
required
integer >= 1

Certificate ID

Responses

Response samples

Content type
application/json
{
  • "owner_id": 1,
  • "certificate_type_id": 1,
  • "owner_type": "user",
  • "classification": "Cereals",
  • "issued_by": "string",
  • "reference": "RR123456",
  • "start_date": "2019-08-24",
  • "renewal_date": "2019-08-24",
  • "attachment": {},
  • "is_private": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Update certificate.

Updates a certificate for user/organisation.

path Parameters
id
required
integer >= 1

Certificate ID

Request Body schema: application/json
owner_id
required
integer >= 1

Owner ID either of user or organisation.

certificate_type_id
required
integer >= 1

Certificate type ID (Cert Type API).

classification
string

Scope/classification of this certificate.

issued_by
string

Issuer institute/org. of the certificate.

reference
required
string

Reference number given to the certificate.

start_date
required
string <date>

Start date of validation of the certificate.

renewal_date
required
string <date>

Renewal date of validation of the certificate.

object (Attachment)

File upload object with file_name and url of attachment.

is_private
required
boolean

If the certificate is private or public.

Responses

Request samples

Content type
application/json
{
  • "owner_id": 1,
  • "certificate_type_id": 1,
  • "classification": "Cereals",
  • "issued_by": "string",
  • "reference": "RR123456",
  • "start_date": "2019-08-24",
  • "renewal_date": "2019-08-24",
  • "attachment": {},
  • "is_private": true
}

Response samples

Content type
application/json
{
  • "owner_id": 1,
  • "certificate_type_id": 1,
  • "owner_type": "user",
  • "classification": "Cereals",
  • "issued_by": "string",
  • "reference": "RR123456",
  • "start_date": "2019-08-24",
  • "renewal_date": "2019-08-24",
  • "attachment": {},
  • "is_private": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

List of certificate types.

Gets a list of certificate types for user/organisation.

query Parameters
is_personal
boolean

Certificate Type is of type personal(i.e user).

search
string
Example: search=AP

Text search by name of certificate.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "AP Number"
}

Notification

Push notifications

Register device

Register a device for Firebase notifications

Request Body schema: application/json
token
required
string
Default: "Firebase token"
device_type
required
string
Default: "Device type"
Enum: "ios" "android"
device_id
string
Default: "Unique device identifier"

Responses

Request samples

Content type
application/json
{
  • "token": "Firebase token",
  • "device_type": "ios",
  • "device_id": "Unique device identifier"
}

Delete device

Delete a device that was saved for Firebase notifications

Request Body schema: application/json
token
string

Firebase token. If this is not present in request body, all the tokens gets deleted that were stored for the requesting user

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Retrieve user notification preferences

Defines what notification preferences the user has set.

Responses

Response samples

Content type
application/json
{
  • "crop_monitoring_diaries": true
}

Update user notification preferences

Update the user's notification preferences.

Request Body schema: application/json
crop_monitoring_diaries
required
boolean

Whether the user will recieve crop monitoring diary notifications.

Responses

Request samples

Content type
application/json
{
  • "crop_monitoring_diaries": true
}

Upload

File attachment upload

Upload media file

Media files are public and shareable, but not searchable. The filename is replaced with a 16-digit generated UUID but with the same suffix. Geolocation data can be supplied as a latitude and longitude (if supplied then both are required). If not supplied then we will look for geolocation data inside the EXIF tags. If both are supplied then EXIF data takes precendence.

Request Body schema: multipart/form-data
file
required
string <binary>

Binary file

file_name
required
string

File name

longitude
number <float>

Longitude

latitude
number <float>

Latitude

Responses

Response samples

Content type
application/json
{}

Country

List of countries.

List countries

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Organisation

Organisation management

List organisations

List of paginated organisations with search and sort by name

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

is_connected
boolean

If true then only include organisations that are connected to the requester's organisation. Note that we always treat our own organisation as connected. Falsey values are ignored.

is_supplier
boolean

If true then only include organisations which are sellers (i.e suppliers) in any trading agreements to the user's organisation. If false then exclude all organisations which act as sellers in any trading agreements visible to the user's organisation.

search
string

Search for name

name
string

Filter by exact name match

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create an organisation

Creates an organisation and a team with the same name, it also creates a connection between the requester org and the created org with can manage permission from the requester org (Auth - KH staff user and reg admins only).

Request Body schema: application/json
Any of
reference
string

An ID number/code provided by a government agency/authority in a given region. We are not verifying it.

is_farm
boolean

Whether this organisation has fields in which they might possibly farm.

website
string <uri>

Website uri of the organisation

phone
string

Phone number of the organisation

email
string <email>

Email address of the organisation

object (Address)

Address

name
required
string

Name of the organisation. Should be globally unique.

Responses

Request samples

Content type
application/json
Example
{
  • "reference": "FNAF123",
  • "is_farm": true,
  • "website": "https://kisanhub.com/",
  • "phone": "+41836736373",
  • "email": "example@gmail.com",
  • "address": {
    },
  • "name": "ABC Inc."
}

Response samples

Content type
application/json
{
  • "reference": "FNAF123",
  • "is_farm": true,
  • "website": "https://kisanhub.com/",
  • "phone": "+41836736373",
  • "email": "example@gmail.com",
  • "address": {
    },
  • "id": 1,
  • "name": "ABC Inc.",
  • "logo": {},
  • "team": {
    }
}

List organisation connections

Get the list of all organisation connections of authorised user's organisation.

query Parameters
is_active
boolean

Filter for active or inactive connections only. If not provided, all connections will be returned

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create organisation connection

Connects an organisation with another organisation. Note that this is only available to customer organisations and KisanHub staff

Request Body schema: application/json
connect_to
required
integer

ID of the organisation to connect to.

Responses

Request samples

Content type
application/json
{
  • "connect_to": 0
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "organisation_id": 1,
  • "can_manage": true,
  • "is_active": true,
  • "is_sharing_diaries": true
}

Disconnect organisation

Deactivate a connection from one organisation to another

path Parameters
id
required
integer >= 1

Organisation connection id

Responses

Update network connection

Update a connection between two organisations

path Parameters
id
required
integer >= 1

Organisation connection id

Request Body schema: application/json
is_sharing_diaries
boolean

If true then the "from" organisation of this connection is allowing the target organisation to view crop monitoring diaries that users of their organisation have created for any plot that the target organisation can see.

Responses

Request samples

Content type
application/json
{
  • "is_sharing_diaries": true
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "organisation_id": 1,
  • "can_manage": true,
  • "is_active": true,
  • "is_sharing_diaries": true
}

Get an organisation

Get an organisation detail (Auth - all users).

path Parameters
id
required
integer >= 1

Organisation id

Responses

Response samples

Content type
application/json
{
  • "reference": "FNAF123",
  • "is_farm": true,
  • "website": "https://kisanhub.com/",
  • "phone": "+41836736373",
  • "email": "example@gmail.com",
  • "address": {
    },
  • "id": 1,
  • "name": "ABC Inc.",
  • "logo": {},
  • "team": {
    }
}

Update an organisation

Update an organisation (Auth - KH staff, org members and members of manager orgs).

path Parameters
id
required
integer >= 1

Organisation id

Request Body schema: application/json
Any of
reference
string

An ID number/code provided by a government agency/authority in a given region. We are not verifying it.

is_farm
boolean

Whether this organisation has fields in which they might possibly farm.

website
string <uri>

Website uri of the organisation

phone
string

Phone number of the organisation

email
string <email>

Email address of the organisation

object (Address)

Address

name
required
string

Name of the organisation. Should be globally unique.

Responses

Request samples

Content type
application/json
Example
{
  • "reference": "FNAF123",
  • "is_farm": true,
  • "website": "https://kisanhub.com/",
  • "phone": "+41836736373",
  • "email": "example@gmail.com",
  • "address": {
    },
  • "name": "ABC Inc."
}

Response samples

Content type
application/json
{
  • "reference": "FNAF123",
  • "is_farm": true,
  • "website": "https://kisanhub.com/",
  • "phone": "+41836736373",
  • "email": "example@gmail.com",
  • "address": {
    },
  • "id": 1,
  • "name": "ABC Inc.",
  • "logo": {},
  • "team": {
    }
}

User report

Flattened report of organisations and users in CSV format

Responses

Organisation network

Organisation network management

Organisation network report

Summary report for all connections in the network of the requesting user's organisation.

query Parameters
group_id
integer >= 1

List only those network connections that have been assigned to the requested organisation-group

organisation_id
integer >= 1

List only the network connection associated with the requested organisation

is_active
boolean

Filter for active or inactive connections only. If not provided, all connections will be returned

role
string
Enum: "agronomist" "field-officer"

Role assigned to an advisor.

advisor_user_id
integer (PrimaryKey) >= 1
Example: advisor_user_id=1

User assigned to an advisor role for a connected organisation.

source_organisation_id
integer

Source organisation ID. Ignored if connection_id is supplied. May only be used by KisanHub staff

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Organisation group

Organisation group

List organisation groups

Retrieve the list of organisation-groups for the requesting user's organisation.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an organisation-group

Creates a new organisation group to which organisations in the user's network can be assigned. Users can only create organisation-groups for the organisation to which they belong.

Request Body schema: application/json
name
required
string

The name to be given to the organisation-region

Responses

Request samples

Content type
application/json
{
  • "name": "West region"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "West region",
  • "owner_id": 1
}

Retrieve an organisation group

Retrieve an organisation group by it's ID.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "West region",
  • "owner_id": 1
}

Partially update an existing organisation-group

Updates the name of an existing organisation group. Users can only update organisation-groups that belong their organisation.

path Parameters
id
required
integer >= 1

Organisation-group id

Request Body schema: application/json
name
required
string

The name to be given to the organisation-region

Responses

Request samples

Content type
application/json
{
  • "name": "West region"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "West region",
  • "owner_id": 1
}

Delete an organisation-group

Delete an existing organisation group by ID. Users can only delete organisation-groups that belong their organisation.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Assign an organisation to an organisation-group

Assigns an organisation to an organisation group. Users can only assign organisation-groups owned by the organisation to which they belong. Users can only assign one organisation-group to each organisation in their network.

path Parameters
group_id
required
integer >= 1
Example: 2

id of the organisation-group being assigned

organisation_id
required
integer >= 1
Example: 3

id of the organisation being assigned to the group

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "group_id": 1,
  • "organisation_id": 1
}

Remove the assignment of an organisation-group to an organisation

Delete an existing assignment of an organisation-group to an organisation using the group_id & organisation_id Users can only delete assignments for organisation-groups that belong to their organisation.

path Parameters
group_id
required
integer >= 1
Example: 2

id of the organisation-group being unassigned

organisation_id
required
integer >= 1
Example: 3

id of the organisation being removed from the group

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Organisation groups usage summary

Retrieve the list of organisation-groups for the requesting user's organisation, with a summary representation that includes a count of assignments (usage).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Organisation advisor

Organisation group

List organisation advisors

List of assigned advisors by an organisation.

query Parameters
connection_id
integer (PrimaryKey) >= 1
Example: connection_id=1

Connection ID

role
string
Enum: "agronomist" "field-officer"

Role assigned to an advisor.

advisor_user_id
integer (PrimaryKey) >= 1
Example: advisor_user_id=1

User assigned to an advisor role for a connected organisation.

source_organisation_id
integer

Source organisation ID. Ignored if connection_id is supplied. May only be used by KisanHub staff

assigned_organisation_id
integer (PrimaryKey) >= 1
Example: assigned_organisation_id=1

ID of organisation in the assigning Organisation's network to which an advisor is assigned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Assign advisor

Assign a user to an advisor role for an organisation in your network.

Request Body schema: application/json
connection_id
integer

Connection ID

source_organisation_id
integer

Source organisation ID. Ignored if connection_id is supplied. May only be used by KisanHub staff

target_organisation_id
integer

Target organisation ID. Ignored if connection_id is supplied. Must refer to a connected organisation

role
required
string (AdvisorRole)
Enum: "agronomist" "field-officer"

Role of the advisor assigned.

user_id
required
integer

Advisor user ID

Responses

Request samples

Content type
application/json
{
  • "connection_id": 0,
  • "source_organisation_id": 0,
  • "target_organisation_id": 0,
  • "role": "agronomist",
  • "user_id": 0
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "source_org_id": 1,
  • "target_org_id": 1,
  • "role": "agronomist",
  • "user_id": 1
}

Get organisation advisor

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Change advisor

Change the advisor assigned to an organisation connection

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "user_id": 1
}

Clear advisor

Clear the advisor assigned to an organisation connection

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Trading agreement

Trading agreement management of organisations.

Returns a list of trading agreement reports.

Trading agreements involving the authenticated user's organisation, ordered by latest start_date.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

is_active
boolean

If true then only return agreements that are currently active i.e start_date <= today <= end_date. If not specified then return all agreements.

organisation_id
integer >= 1
Example: organisation_id=1

Returns agreements matching either the buyer or the seller organisation ID

buyer_id
integer >= 1
Example: buyer_id=1

Returns agreements matching either the buyer organisation ID

seller_id
integer >= 1
Example: seller_id=1

Returns agreements matching either the seller organisation ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

tag_ids
Array of integers
Example: tag_ids=2,3

Comma-separated list of crop tag IDs. Includes objects that have been tagged with any of these tags

tag_id
integer >= 1

Filter by crop tag ID. Include objects that have been tagged with this tag.

search
string
Example: search=kisan

Text search by Organisation name, address, post code or phone number of the buyer or seller.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Returns a single trading agreement report

Returns a trading agreement (i.e contract) by id

path Parameters
id
required
integer >= 1

Trading agreement ID

Responses

Response samples

Content type
application/json
{
  • "reference": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "tonnage": 0,
  • "email_recipients": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "buyer": {
    },
  • "seller": {
    },
  • "crop": {
    },
  • "tags": [
    ]
}

Create a sales/purchase agreement with another organisation.

Request Body schema: application/json
reference
required
string

reference of original agreement between the buyer and seller.

start_date
required
string <date>
end_date
required
string <date>
tonnage
required
integer

The amount of produce being traded.

email_recipients
Array of strings (EmailRecipients) <= 10 items

list of email addresses that load tickets will be sent to.

buyer_id
required
integer >= 1

ID of the buyer organisation.

seller_id
required
integer >= 1

ID of the seller organisation.

additional_party_id
integer >= 1

ID of the "additional party" organisation. This organisation is allowed to view this agreement as well as load tickets linked to this agreement.

crop_id
required
integer >= 1

Crop (i.e genus) ID

tag_ids
Array of integers

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "reference": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "tonnage": 0,
  • "email_recipients": [
    ],
  • "buyer_id": 1,
  • "seller_id": 1,
  • "additional_party_id": 1,
  • "crop_id": 1,
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "reference": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "tonnage": 0,
  • "email_recipients": [
    ],
  • "buyer_id": 1,
  • "seller_id": 1,
  • "additional_party_id": 1,
  • "crop_id": 1,
  • "tag_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Retrieve a single trading agreement.

path Parameters
id
required
integer >= 1

Trading agreement ID

Responses

Response samples

Content type
application/json
{
  • "reference": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "tonnage": 0,
  • "email_recipients": [
    ],
  • "buyer_id": 1,
  • "seller_id": 1,
  • "additional_party_id": 1,
  • "crop_id": 1,
  • "tag_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Delete a trading agreement.

Only trading agreements with no associated trade records may be deleted.

path Parameters
id
required
integer >= 1

Trading agreement ID

Responses

Update a trading agreement.

path Parameters
id
required
integer >= 1

Trading agreement ID

Request Body schema: application/json
reference
required
string

reference of original agreement between the buyer and seller.

start_date
required
string <date>
end_date
required
string <date>
tonnage
required
integer

The amount of produce being traded.

email_recipients
Array of strings (EmailRecipients) <= 10 items

list of email addresses that load tickets will be sent to.

buyer_id
required
integer >= 1

ID of the buyer organisation.

seller_id
required
integer >= 1

ID of the seller organisation.

additional_party_id
integer >= 1

ID of the "additional party" organisation. This organisation is allowed to view this agreement as well as load tickets linked to this agreement.

crop_id
required
integer >= 1

Crop (i.e genus) ID

tag_ids
Array of integers

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "reference": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "tonnage": 0,
  • "email_recipients": [
    ],
  • "buyer_id": 1,
  • "seller_id": 1,
  • "additional_party_id": 1,
  • "crop_id": 1,
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "reference": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "tonnage": 0,
  • "email_recipients": [
    ],
  • "buyer_id": 1,
  • "seller_id": 1,
  • "additional_party_id": 1,
  • "crop_id": 1,
  • "tag_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1
}

Retrieve the number of associated trade records

path Parameters
id
required
integer >= 1

Trading agreement ID

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

List delivery destinations

Returns a list of delivery destinations (organisations) sorted by name for a given trading agreement. This will return a list of Organisations which satisfies any of these conditions:

  • The organisation is the buyer from this agreement
  • Buyer organisations of all trading agreements where the seller is the buyer of this agreement
path Parameters
id
required
integer >= 1

trading agreement ID.

Responses

Response samples

Content type
application/json
[]

Organisation permissions

Organisation permissions

List organisation permissions

Staff-only API to list organisation permissions

query Parameters
is_customer
boolean

If set then only return organisations that are KisanHub customers (i.e have valid subscriptions)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get organisation permissions

Staff-only API to get permissions for a single organisation

path Parameters
id
required
integer (OrganisationId) >= 1

Organisation ID

Responses

Response samples

Content type
application/json
{
  • "organisation_id": 0,
  • "organisation_name": "string",
  • "is_customer": true,
  • "monitor": true,
  • "supply": true,
  • "quality": true,
  • "reports": true
}

Set organisation permissions

Staff-only API to set organisation permissions

path Parameters
id
required
integer (OrganisationId) >= 1

Organisation ID

Request Body schema: application/json
organisation_id
number

Organisation Id

is_customer
boolean

True if this is a KisanHub customer with a valid subscription

monitor
boolean

True to allow access to Crop Monitoring

supply
boolean

True to allow access to Supply Chain

quality
boolean

True to allow access to Quality

reports
boolean

True to allow access to Reports

Responses

Request samples

Content type
application/json
{
  • "organisation_id": 0,
  • "is_customer": true,
  • "monitor": true,
  • "supply": true,
  • "quality": true,
  • "reports": true
}