KisanHub API (1.0)

Download OpenAPI specification:Download

API Support: support@kisanhub.com

Introduction

Welcome to the KisanHub developer hub. 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.

Authentication

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

Authorization: Token <token>

You'll find your token in the settings page in the main application (Europe and RoW or India)

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. We use metric units throughout e.g we use hectares for area.

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
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.
Crop The produce cropped from a field
Genus The genus of the planted crop e.g "Potato"
Variety The variety of the planted crop e.g "Adora"
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
Load Ticket A record of a load transaction that is sent to the customer and verified at intake

user

User management

List users

The list of accessible users will depend on the access rights of the requesting user. A user will always be able to view user details for members of their own team. A user with the SITE_ADMIN permission in an Enterprise team will be able to view users of client teams. A user with the FIELD_OPERATOR permission will be allowed to optionally view all users of teams which have shared information with them via the "include_collaborators" query parameter. A Kisanhub staff member will be able to view all users.

query Parameters
page
integer >= 1
Default: 1

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

search
string

Search for name or phone number

team_id
integer

Filters by team ID

user_type
string
Enum: "grower" "agronomist"

Filter on the user type

include_collaborators
boolean
Default: false

Include users from teams that have shared information with the requesting user or with the team of the requesting user. This option is only available for users with the FIELD_OFFICER permission level.

Responses

200

Return a list of user details

403

Unauthorized

get /api/user

UK server

https://app.kisanhub.com/api/user

India server

https://app.kisanhub.in/api/user

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

first_name
required
string

First (and middle) name

last_name
required
string

Last name

email
string

Email

team_id
required
integer

Primary team key

contact_details
object

Contact details

demographics
object

Demographical user information

grower_details
object
address
object
password
required
string <password>

Responses

201

User was successfully created

400

Bad user

403

Unauthorized

post /api/user

UK server

https://app.kisanhub.com/api/user

India server

https://app.kisanhub.in/api/user

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "team_id": 0,
  • "contact_details":
    {
    },
  • "demographics":
    {
    },
  • "grower_details":
    {
    },
  • "address":
    {
    },
  • "password": "pa$$word"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 1,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "team_id": 0,
  • "contact_details":
    {
    },
  • "demographics":
    {
    },
  • "grower_details":
    {
    },
  • "address":
    {
    }
}

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 >= 1

User ID

Responses

200

OK

403

Unauthorized

get /api/user/{id}

UK server

https://app.kisanhub.com/api/user/{id}

India server

https://app.kisanhub.in/api/user/{id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 1,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "team_id": 0,
  • "contact_details":
    {
    },
  • "demographics":
    {
    },
  • "grower_details":
    {
    },
  • "address":
    {
    }
}

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 >= 1

User ID

Request Body schema: application/json
username
required
string

Globally unique username

first_name
required
string

First (and middle) name

last_name
required
string

Last name

email
string

Email

team_id
required
integer

Primary team key

contact_details
object

Contact details

demographics
object

Demographical user information

grower_details
object
address
object

Responses

200

OK

400

Bad request

403

Unauthorized

put /api/user/{id}

UK server

https://app.kisanhub.com/api/user/{id}

India server

https://app.kisanhub.in/api/user/{id}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "team_id": 0,
  • "contact_details":
    {
    },
  • "demographics":
    {
    },
  • "grower_details":
    {
    },
  • "address":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 1,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "team_id": 0,
  • "contact_details":
    {
    },
  • "demographics":
    {