Farmforce API Documentation

This document describes version v0 of the Farmforce API

1.0 Overview
Farmforce provides an API for clients who wish to access data programmatically. For example, by selecting the view “Farmer”, the client can
retrieve a list of records containing farmer data, such as name, mobile number and village. Almost all Farmforce views are available through the
API (a list of available views is provided by the API itself).

The Farmforce API is based on the REST standard, where URLs represent data and actions on the data are performed using http verbs (such as
GET for retrieving data and POST for creating data). Any programming language capable of performing HTTPS requests can be used. Data
returned from API uses the JSON stardard, with UTF-8 encoding.

Clients using the API must be authenticated, by using a Farmforce username and password, and requests are rate-limited (currently the limit is 50
requests per hour).

In the rest of this guide, all example calls will assume we are using the following tenant URL:

https://test.farmforce.com/

2.0 Available Views

A list of available views can be retrieved using the views url. All requests should be done using https, as the API is not available over http.
Authentication must use Basic HTTP Auth for all requests.

Call for retrieving available views

GET https://test.farmforce.com/api/v0/views?format=json

The response will include the name of each view, along with the URL used to retrieve its data:

Available views response sample

Below is a table with currently available views in the API:

View name Resource URI

1 account_balances /api/v0/view/account_balances/

2 active-farmers /api/v0/view/active-farmers/

3 api_log /api/v0/view/api_log/

4 apipermission_changelog /api/v0/view/apipermission_changelog/

5 applets /api/v0/view/applets/

6 auth_group /api/v0/view/auth_group/

7 auth_user /api/v0/view/auth_user/

8 authorisation_for_chemical_applications /api/v0/view/authorisation_for_chemical_applications/

9 bin-card-example /api/v0/view/bin-card-example/
10 buyers /api/v0/view/buyers/

11 certification_states /api/v0/view/certification_states/

12 certifications /api/v0/view/certifications/

13 chemical_targets /api/v0/view/chemical_targets/

14 chemicals /api/v0/view/chemicals/

15 climate_conditions /api/v0/view/climate_conditions/

16 companies /api/v0/view/companies/

17 compliance_categories /api/v0/view/compliance_categories/

18 compliance_questions_ranking /api/v0/view/compliance_questions_ranking/

19 conflict_tickets_view /api/v0/view/conflict_tickets_view/

20 countries /api/v0/view/countries/

21 crop_categories /api/v0/view/crop_categories/

22 crop_protocol_templates /api/v0/view/crop_protocol_templates/

23 crop_varieties /api/v0/view/crop_varieties/

24 cropping_cycle_financials /api/v0/view/cropping_cycle_financials/

25 crops /api/v0/view/crops/

26 device_binary_view /api/v0/view/device_binary_view/

27 device_logs /api/v0/view/device_logs/

28 device_registry /api/v0/view/device_registry/

29 device_sync_sessions /api/v0/view/device_sync_sessions/

30 device_synccommandrequests /api/v0/view/device_synccommandrequests/

31 device_synchronization /api/v0/view/device_synchronization/

32 devices /api/v0/view/devices/

33 devices_unregistered /api/v0/view/devices_unregistered/

34 employers /api/v0/view/employers/

35 equipment /api/v0/view/equipment/

36 farm /api/v0/view/farm/

37 farmer_certifications /api/v0/view/farmer_certifications/

38 farmer_compliance /api/v0/view/farmer_compliance/

39 farmer_last_activity /api/v0/view/farmer_last_activity/

40 farmer_premiums /api/v0/view/farmer_premiums/

41 farmer_proposed_actions /api/v0/view/farmer_proposed_actions/

42 farmer_scorecard_analysis /api/v0/view/farmer_scorecard_analysis/

43 farmercertifications_fieldquotas /api/v0/view/farmercertifications_fieldquotas/

44 farmer-details-more /api/v0/view/farmer-details-more/

45 farmer-email /api/v0/view/farmer-email/

46 farmers /api/v0/view/farmers/
47 farmers_staff /api/v0/view/farmers_staff/

48 farmers-and-field /api/v0/view/farmers-and-field/

49 farming_operators /api/v0/view/farming_operators/

50 farms /api/v0/view/farms/

51 fertilizers /api/v0/view/fertilizers/

52 fftenant_messagereceivetrigger /api/v0/view/fftenant_messagereceivetrigger/

53 fftenant_messagetriggeraction /api/v0/view/fftenant_messagetriggeraction/

54 field_size_discrepancy /api/v0/view/field_size_discrepancy/

55 field_size_discrepancy_assumed /api/v0/view/field_size_discrepancy_assumed/

56 field-productivity.DashboardWidget /api/v0/view/field-productivity.DashboardWidget/

57 fields /api/v0/view/fields/

58 ga_costs /api/v0/view/ga_costs/

59 ga_equipment_cost /api/v0/view/ga_equipment_cost/

60 ga_operator_cost /api/v0/view/ga_operator_cost/

61 group_loans /api/v0/view/group_loans/

62 groups_view /api/v0/view/groups_view/

63 grower_and_harvest_information /api/v0/view/grower_and_harvest_information/

64 growing_activities_operator_view /api/v0/view/growing_activities_operator_view/

65 growing_activity_alerts /api/v0/view/growing_activity_alerts/

66 growing_activity_types /api/v0/view/growing_activity_types/

67 growth_stages /api/v0/view/growth_stages/

68 ha_costs /api/v0/view/ha_costs/

69 harvest_collection_bin_brands /api/v0/view/harvest_collection_bin_brands/

70 harvest_collection_bin_types /api/v0/view/harvest_collection_bin_types/

71 harvest_collection_containers /api/v0/view/harvest_collection_containers/

72 harvest_collection_locations /api/v0/view/harvest_collection_locations/

73 harvest_collection_types /api/v0/view/harvest_collection_types/

74 harvest_collections /api/v0/view/harvest_collections/

75 harvest_sale_per_farmer /api/v0/view/harvest_sale_per_farmer/

76 harvest_sales /api/v0/view/harvest_sales/

77 harvest_warehouse_view /api/v0/view/harvest_warehouse_view/

78 harvest-information /api/v0/view/harvest-information/

79 harvesting_activities_operator_view /api/v0/view/harvesting_activities_operator_view/

80 harvesting_activity_alerts /api/v0/view/harvesting_activity_alerts/

81 harvests_and_loans /api/v0/view/harvests_and_loans/

82 harvest-warehouse-summary /api/v0/view/harvest-warehouse-summary/

83 hc_weight_change_reasons /api/v0/view/hc_weight_change_reasons/
84 hc-bin-type-and-brand /api/v0/view/hc-bin-type-and-brand/

85 hs_per_field /api/v0/view/hs_per_field/

86 impersonator-log /api/v0/view/impersonator-log/

87 input_groups /api/v0/view/input_groups/

88 input_storage_warehouse_view /api/v0/view/input_storage_warehouse_view/

89 input_usage /api/v0/view/input_usage/

90 input_warehouse_inventory /api/v0/view/input_warehouse_inventory/

91 input-list-for-input-loans /api/v0/view/input-list-for-input-loans/

92 input-list-totals /api/v0/view/input-list-totals/

93 inventory_disposal_reason /api/v0/view/inventory_disposal_reason/

94 inventory_items /api/v0/view/inventory_items/

95 json_changelog /api/v0/view/json_changelog/

96 loan_products /api/v0/view/loan_products/

97 loan_repayments /api/v0/view/loan_repayments/

98 loans /api/v0/view/loans/

99 manufacturers /api/v0/view/manufacturers/

100 mdb_field /api/v0/view/mdb_field/

101 mdb_field_type /api/v0/view/mdb_field_type/

102 mdb_link /api/v0/view/mdb_link/

103 mdb_x2n_selector /api/v0/view/mdb_x2n_selector/

104 misc_link /api/v0/view/misc_link/

105 mobile_db_views /api/v0/view/mobile_db_views/

106 MobileBinary.SysAdmin /api/v0/view/MobileBinary.SysAdmin/

107 my_tasks /api/v0/view/my_tasks/

108 outgoing_emails /api/v0/view/outgoing_emails/

109 payment_types /api/v0/view/payment_types/

110 planting_campaign_groups /api/v0/view/planting_campaign_groups/

111 planting_campaign_templates /api/v0/view/planting_campaign_templates/

112 planting_campaigns /api/v0/view/planting_campaigns/

113 purchase_traceability /api/v0/view/purchase_traceability/

114 purchases-per-buyer /api/v0/view/purchases-per-buyer/

115 reciepts /api/v0/view/reciepts/

116 reports /api/v0/view/reports/

117 savings /api/v0/view/savings/

118 sms_delivery_failed /api/v0/view/sms_delivery_failed/

119 sms_incoming /api/v0/view/sms_incoming/

120 sms_outgoing /api/v0/view/sms_outgoing/

 121 sms_outgoing_bulk /api/v0/view/sms_outgoing_bulk/

122 sms_outgoing_individual /api/v0/view/sms_outgoing_individual/

123 staff /api/v0/view/staff/

124 staff_log /api/v0/view/staff_log/

125 staff_survey_responses /api/v0/view/staff_survey_responses/

126 Store.Select /api/v0/view/Store.Select/

127 subscription_log /api/v0/view/subscription_log/

128 survey /api/v0/view/survey/

129 survey-results /api/v0/view/survey-results/

130 survey-results-available /api/v0/view/survey-answers/

131 surveys /api/v0/view/surveys/

132 surveys_by_staff /api/v0/view/surveys_by_staff/

133 sync_conflicts /api/v0/view/sync_conflicts/

134 tags /api/v0/view/tags/

135 tasks /api/v0/view/tasks/

136 trainer_groups /api/v0/view/trainer_groups/

137 trainers /api/v0/view/trainers/

138 training_events /api/v0/view/training_events/

139 training_topics /api/v0/view/training_topics/

140 trainings /api/v0/view/trainings/

141 units /api/v0/view/units/

142 va_currency /api/v0/view/va_currency/

143 va_transactions /api/v0/view/va_transactions/

144 virtual_account_types /api/v0/view/virtual_account_types/

145 vnp-farmers /api/v0/view/vnp-farmers/

146 vnp-fields /api/v0/view/vnp-fields/

147 vnp-planting-campaigns /api/v0/view/vnp-planting-campaigns/

148 weekly_yield_forecasts /api/v0/view/weekly_yield_forecasts/

149 yield_forecasts_per_field /api/v0/view/yield_forecasts_per_field/

3.0 Retrieving data from the server

Each one of the available views can be accessed by concatenating the base URL of the tenant (i.e. https://test.farmforce.com), the Resource URI
of the view we are trying to access (i.e. /api/v0/view/farmers/) and a directive to specify the format we wish for the result (?format=json or ?format
=xml).

A call to retrieve a list of farmers would therefore have the following form:
 Retrieving list of farmers

GET https://test.farmforce.com/api/v0/view/farmers/?format=json

There is a limit of records that can be retrieved in each call to the API, currently this limit is 500 records.

A typical response will be:

{"columns":
[
"Photo", "Farmer ID", "First Name", "Last Name", "Mobile Number",
"Certification ID", "Village", "Groups", "Farmer Tags", "Creation Date",
"Last Modified Date"
], "data":
[
{
"id": 4243,
"object": "+16185550103",
"row":
[
"", "PN3.1.13", "", "", "+16185550103", null, null, "", "",
"2013-11-26T09:36:14", "2013-11-26T09:36:14"
]
}, {
"id": 4252,
"object": "Cesaro Antonio",
"row":
[
"", "PN3.1.26", "Cesaro", "Antonio", "+14245550102", null, "Gansa",
"", "\"Maize\",\"detailed\",\"testing\"", "2015-07-14T11:37:41.403906",
"2016-02-09T16:45:46.193250"
]}, {
"id": 176,
"object": "Daniel Barasa",
"row":
[
"", "PN5*35*6", "Daniel", "Barasa", "+12095550101", null,
"Korkorla", "Insured farmers group", "\"detailed\"",
"2013-01-08T00:00:00", "2015-06-15T11:06:10.649198"
]
}
]
}
A response will contain a columns section with a single record containing the field names of the returned data and a data section with all the
respective records. Each record will have an id and an object field with a text representation of the record (this varies per view) and a row field
which will contain the actual data of the record corresponding to the field names in the columns section.

3.1 API call options

A number of options can be used to refine an API call. Here is a description of these options:

limit

Each API call can return a maximum of 500 records. However, we can define exactly how many records we wish to retrieve by setting the
limit in the Resource URI:

Setting the limit to 20 records

GET https://test.farmforce.com/api/v0/view/farmers/?format=json&limit=20

Default: 10, Maximum: 500

page

By default, each API call will return the 10 first records (or whatever the limit is set to) and this will be the first page of results. If we wish to
access the next page of records (11 to 20), we use the page option as follows:

Retrieving second page of results

GET https://test.farmforce.com/api/v0/view/farmers/?format=json&page=2

Default: 1

format

This is used to select one of the two available formats for returning data.

Possible values: json, xml

text filtering

We may filter the returning results by specifying values for text columns in the returning dataset. We can filter by searching an exact match
to a column, i.e. search for farmers with first name "Cesaro":

Retrieving farmers by first name

GET
https://test.farmforce.com/api/v0/view/farmers/?format=json&column_1_equ
als=Cesaro
or we can filter by a partial match, i.e. search for farmers with IDs that contain PN3.1:

Retrieving farmers by ID partial match

GET
https://test.farmforce.com/api/v0/view/farmers/?format=json&column_0_con
tains=PN3.1

number filtering

If we want to filter by numeric columns, we can use the equals switch as in text filtering or we can use two additional switched, valid for
numbers only: greater_than and lesser_than. These can be used separetely (i.e. all harvest collections with balance greater or equal to 5)
or together to define a range (i.e. all harvest collections with balance between 1000 and 3000)

Number filtering

GET
https://test.farmforce.com/api/v0/view/harvest_collections/?format=json&
column_10_greater_than=20
GET
https://test.farmforce.com/api/v0/view/harvest_collections/?format=json&
column_10_greater_than=1000&column_10_lesser_than=3000