API Reference

Farms

Create and manage the farms owned by a user on the platform.

post/farms/create

Create a farm without an organization (any authenticated user)

Requires an Authorization: Bearer header.

Request body

namestringrequired

farm_typeenum<string>optional

smallholdercommercialcooperativeoutgrowercorporate

farm_sizeenum<string>optional

microsmallmediumlargeenterprise

tenure_typeenum<string>optional

Enum for tenure types

ownedleasedsharedrented

has_irrigationbooleanoptional

irrigation_typeenum<string>optional

Enum for irrigation types

dripsprinklerfloodsurfacenone

water_sourceenum<string>optional

Enum for water source types

riverwellboreholerainfedothers

common_grown_cropsstring[]optional

soil_typeenum<string>optional

Enum for soil types

claysandyloamysiltypeatychalkyunknown

currencystringoptional

locationstringoptional

countrystringoptional

Response 201

farm_idstringrequired

cropsense_farm_idstringoptional

namestringrequired

owner_idstringrequired

registered_by_org_idstringoptional

farm_typeenum<string>optional

smallholdercommercialcooperativeoutgrowercorporate

farm_sizeenum<string>optional

microsmallmediumlargeenterprise

tenure_typeenum<string>optional

Enum for tenure types

ownedleasedsharedrented

has_irrigationbooleanrequired

irrigation_typeenum<string>optional

Enum for irrigation types

dripsprinklerfloodsurfacenone

water_sourceenum<string>optional

Enum for water source types

riverwellboreholerainfedothers

common_grown_cropsstring[]optional

soil_typeenum<string>optional

Enum for soil types

claysandyloamysiltypeatychalkyunknown

currencystringoptional

locationstringoptional

countrystringoptional

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

farmerFarmerProfileoptional

Farmer identity returned in farm responses.

organizationsFarmLinkedOrganization[]optional

POST /farms/create

curl -X POST "https://api.cropsense.africa/farms/create" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Green Valley Farm",
    "farm_type": "smallholder",
    "farm_size": "micro",
    "tenure_type": "owned",
    "has_irrigation": false,
    "irrigation_type": "drip",
    "water_source": "river",
    "common_grown_crops": [
      "common_grown_crops"
    ],
    "soil_type": "clay",
    "currency": "USD",
    "location": "Kiambu County",
    "country": "Kenya"
  }'

Example response · 201

{
  "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
  "cropsense_farm_id": "cropsense_farm_id",
  "name": "Green Valley Farm",
  "owner_id": "d4e2f1a0-9b8c-4a6d-8e3f-2c1b0a9d8e7f",
  "registered_by_org_id": "registered_by_org_id",
  "farm_type": "smallholder",
  "farm_size": "micro",
  "tenure_type": "owned",
  "has_irrigation": true,
  "irrigation_type": "drip",
  "water_source": "river",
  "common_grown_crops": [
    "common_grown_crops"
  ],
  "soil_type": "clay",
  "currency": "USD",
  "location": "Kiambu County",
  "country": "Kenya",
  "is_active": true,
  "created_at": "2026-06-15T09:30:00Z",
  "updated_at": "2026-06-15T09:30:00Z",
  "farmer": {
    "farmer_id": "farmer_id",
    "cropsense_farmer_id": "CS-FARMER-48213",
    "first_name": "first_name",
    "last_name": "last_name",
    "phone_number": "phone_number",
    "language": "language",
    "upload_channel": "upload_channel",
    "whatsapp_number": "whatsapp_number",
    "onboarding_status": "onboarding_status",
    "data_consent_given": true,
    "is_active": true,
    "created_at": "2026-06-15T09:30:00Z",
    "updated_at": "2026-06-15T09:30:00Z"
  },
  "organizations": []
}

get/farms/{farm_id}

Get a farm by id

Requires an Authorization: Bearer header.

Parameters

farm_idstringpathrequired

Response 200

farm_idstringrequired

cropsense_farm_idstringoptional

namestringrequired

owner_idstringrequired

registered_by_org_idstringoptional

farm_typeenum<string>optional

smallholdercommercialcooperativeoutgrowercorporate

farm_sizeenum<string>optional

microsmallmediumlargeenterprise

tenure_typeenum<string>optional

Enum for tenure types

ownedleasedsharedrented

has_irrigationbooleanrequired

irrigation_typeenum<string>optional

Enum for irrigation types

dripsprinklerfloodsurfacenone

water_sourceenum<string>optional

Enum for water source types

riverwellboreholerainfedothers

common_grown_cropsstring[]optional

soil_typeenum<string>optional

Enum for soil types

claysandyloamysiltypeatychalkyunknown

currencystringoptional

locationstringoptional

countrystringoptional

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

farmerFarmerProfileoptional

Farmer identity returned in farm responses.

organizationsFarmLinkedOrganization[]optional

GET /farms/{farm_id}

curl -X GET "https://api.cropsense.africa/farms/3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response · 200

{
  "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
  "cropsense_farm_id": "cropsense_farm_id",
  "name": "Green Valley Farm",
  "owner_id": "d4e2f1a0-9b8c-4a6d-8e3f-2c1b0a9d8e7f",
  "registered_by_org_id": "registered_by_org_id",
  "farm_type": "smallholder",
  "farm_size": "micro",
  "tenure_type": "owned",
  "has_irrigation": true,
  "irrigation_type": "drip",
  "water_source": "river",
  "common_grown_crops": [
    "common_grown_crops"
  ],
  "soil_type": "clay",
  "currency": "USD",
  "location": "Kiambu County",
  "country": "Kenya",
  "is_active": true,
  "created_at": "2026-06-15T09:30:00Z",
  "updated_at": "2026-06-15T09:30:00Z",
  "farmer": {
    "farmer_id": "farmer_id",
    "cropsense_farmer_id": "CS-FARMER-48213",
    "first_name": "first_name",
    "last_name": "last_name",
    "phone_number": "phone_number",
    "language": "language",
    "upload_channel": "upload_channel",
    "whatsapp_number": "whatsapp_number",
    "onboarding_status": "onboarding_status",
    "data_consent_given": true,
    "is_active": true,
    "created_at": "2026-06-15T09:30:00Z",
    "updated_at": "2026-06-15T09:30:00Z"
  },
  "organizations": []
}

put/farms/{farm_id}

Update a farm

Requires an Authorization: Bearer header.

Parameters

farm_idstringpathrequired

Request body

namestringoptional

farm_typeenum<string>optional

smallholdercommercialcooperativeoutgrowercorporate

farm_sizeenum<string>optional

microsmallmediumlargeenterprise

tenure_typeenum<string>optional

Enum for tenure types

ownedleasedsharedrented

has_irrigationbooleanoptional

irrigation_typeenum<string>optional

Enum for irrigation types

dripsprinklerfloodsurfacenone

water_sourceenum<string>optional

Enum for water source types

riverwellboreholerainfedothers

common_grown_cropsstring[]optional

soil_typeenum<string>optional

Enum for soil types

claysandyloamysiltypeatychalkyunknown

currencystringoptional

locationstringoptional

countrystringoptional

updated_atstring<date-time>optional

Response 200

farm_idstringrequired

cropsense_farm_idstringoptional

namestringrequired

owner_idstringrequired

registered_by_org_idstringoptional

farm_typeenum<string>optional

smallholdercommercialcooperativeoutgrowercorporate

farm_sizeenum<string>optional

microsmallmediumlargeenterprise

tenure_typeenum<string>optional

Enum for tenure types

ownedleasedsharedrented

has_irrigationbooleanrequired

irrigation_typeenum<string>optional

Enum for irrigation types

dripsprinklerfloodsurfacenone

water_sourceenum<string>optional

Enum for water source types

riverwellboreholerainfedothers

common_grown_cropsstring[]optional

soil_typeenum<string>optional

Enum for soil types

claysandyloamysiltypeatychalkyunknown

currencystringoptional

locationstringoptional

countrystringoptional

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

farmerFarmerProfileoptional

Farmer identity returned in farm responses.

organizationsFarmLinkedOrganization[]optional

PUT /farms/{farm_id}

curl -X PUT "https://api.cropsense.africa/farms/3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Green Valley Farm",
    "farm_type": "smallholder",
    "farm_size": "micro",
    "tenure_type": "owned",
    "has_irrigation": true,
    "irrigation_type": "drip",
    "water_source": "river",
    "common_grown_crops": [
      "common_grown_crops"
    ],
    "soil_type": "clay",
    "currency": "USD",
    "location": "Kiambu County",
    "country": "Kenya",
    "updated_at": "2026-06-15T09:30:00Z"
  }'

Example response · 200

{
  "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
  "cropsense_farm_id": "cropsense_farm_id",
  "name": "Green Valley Farm",
  "owner_id": "d4e2f1a0-9b8c-4a6d-8e3f-2c1b0a9d8e7f",
  "registered_by_org_id": "registered_by_org_id",
  "farm_type": "smallholder",
  "farm_size": "micro",
  "tenure_type": "owned",
  "has_irrigation": true,
  "irrigation_type": "drip",
  "water_source": "river",
  "common_grown_crops": [
    "common_grown_crops"
  ],
  "soil_type": "clay",
  "currency": "USD",
  "location": "Kiambu County",
  "country": "Kenya",
  "is_active": true,
  "created_at": "2026-06-15T09:30:00Z",
  "updated_at": "2026-06-15T09:30:00Z",
  "farmer": {
    "farmer_id": "farmer_id",
    "cropsense_farmer_id": "CS-FARMER-48213",
    "first_name": "first_name",
    "last_name": "last_name",
    "phone_number": "phone_number",
    "language": "language",
    "upload_channel": "upload_channel",
    "whatsapp_number": "whatsapp_number",
    "onboarding_status": "onboarding_status",
    "data_consent_given": true,
    "is_active": true,
    "created_at": "2026-06-15T09:30:00Z",
    "updated_at": "2026-06-15T09:30:00Z"
  },
  "organizations": []
}

delete/farms/{farm_id}

Soft-delete a farm

Requires an Authorization: Bearer header.

Parameters

farm_idstringpathrequired

DELETE /farms/{farm_id}

curl -X DELETE "https://api.cropsense.africa/farms/3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response · 204

{}

get/farms/farmers/{cropsense_farmer_id}

Look up a farmer and all their farms by shareable farmer ID

Requires an Authorization: Bearer header.

Parameters

cropsense_farmer_idstringpathrequired

Response 200

farmer_idstringrequired

cropsense_farmer_idstringrequired

first_namestringrequired

last_namestringrequired

phone_numberstringoptional

languagestringoptional

upload_channelstringoptional

whatsapp_numberstringoptional

onboarding_statusstringrequired

data_consent_givenbooleanrequired

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

farmsFarmWithFarmer[]optional

total_farmsintegeroptional

GET /farms/farmers/{cropsense_farmer_id}

curl -X GET "https://api.cropsense.africa/farms/farmers/CS-FARMER-48213" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response · 200

{
  "farmer_id": "farmer_id",
  "cropsense_farmer_id": "CS-FARMER-48213",
  "first_name": "first_name",
  "last_name": "last_name",
  "phone_number": "phone_number",
  "language": "language",
  "upload_channel": "upload_channel",
  "whatsapp_number": "whatsapp_number",
  "onboarding_status": "onboarding_status",
  "data_consent_given": true,
  "is_active": true,
  "created_at": "2026-06-15T09:30:00Z",
  "updated_at": "2026-06-15T09:30:00Z",
  "farms": [],
  "total_farms": 0
}