API contracts / App Service v2 / Farmers

One hydrated farmer (get-or-create)

OperationgetFarmer
Call
GET /gateway/urvi-app-service/api/v2/farmers/{farmerId}
Group
Farmers
Features
Farmer hub (option tiles), Add/Edit farmer (IE profile), Notifications, Farmer endorsement details
Replaces today

Use case. Called online when the farmer hub opens with missing data ("Please click here to fetch missing data"), when a notification for an unknown farmer is tapped, and on per-farmer refresh. Accepts a server id or the client UUID; when the UUID matches a master record that has no IE yet, the server creates it (replacing the get-or-create POST on open). include limits the sections returned.

Rules.

  • Farmers outside the user's work nodes -> 404.
  • ETag per farmer; If-None-Match -> 304.

Error codes. NOT_FOUND

Parameters

NameInTypeRequiredMeaningExample
X-App-VersionheaderstringYesApp version `major.minor.patch+build`. Too old -> 426 `VERSION_TOO_OLD`. · pattern ^\d+\.\d+\.\d+(\+\d+)?$2.0.0+200
X-Device-Idheaderstring (uuid)YesApp-scoped device UUID (not ANDROID_ID).6b1f2c3d-0000-4000-8000-00000000d001
X-Request-Idheaderstring (uuid)NoClient-generated request id for tracing; echoed in responses and problems.0e0c5a1b-0000-4000-8000-0000000000a1
Accept-LanguageheaderstringNoLanguage for messages and labels. · one of en, te, ta; default "en"te
X-TenantheaderstringNoTenant code; must match the token. Urvi: `ap.gov`. · one of ap.govap.gov
farmerIdpathstringYesFarmer server id or client UUID (`aliasId`). With a UUID unknown to the server, the farmer is created from the flat master record (get-or-create). · min length 1; max length 643f6c1a2e-0000-4000-8000-00000000f001
includequerystring[]NoSections to include (default all).assets,portfolio,models,plan,metrics
If-None-MatchheaderstringNoETag from a previous response; 304 when unchanged."cfg-2025-26-v41"

Request

No body.

Responses

200 Farmer.

Schema FarmerAggregate.

Example 200 body
{
  "farmer": {
    "id": 700001,
    "clientId": "3f6c1a2e-0000-4000-8000-000000061441",
    "version": 7,
    "createdAt": "2025-06-02T10:00:00+05:30",
    "updatedAt": "2025-10-14T09:30:00+05:30",
    "active": true,
    "ieId": "IE-AP-0000001",
    "name": "Farmer A",
    "gender": "FEMALE",
    "age": 42,
    "mobile": "9000000001",
    "identity": {
      "aadhaarMasked": "XXXX-XXXX-1234",
      "aadhaarSharedWithOther": false
    },
    "maritalStatus": "MARRIED",
    "family": {
      "relation": "SPOUSE",
      "name": "Spouse A",
      "identity": {
        "aadhaarMasked": "XXXX-XXXX-5678"
      }
    },
    "education": "SECONDARY",
    "socialCategory": "BC",
    "village": {
      "id": 3101,
      "type": "VILLAGE",
      "name": "Village A",
      "code": "VIL-3101"
    },
    "habitation": {
      "id": 3901,
      "type": "HABITATION",
      "name": "Habitation A",
      "code": "HAB-3901"
    },
    "vo": {
      "id": 4101,
      "type": "VO",
      "name": "VO A",
      "code": "VO-4101"
    },
    "shg": {
      "id": 52001,
      "type": "SHG",
      "name": "SHG A",
      "code": "SHG-52001"
    },
    "roles": [
      {
        "roleCode": "MEMBER"
      },
      {
        "roleCode": "CADRE",
        "cadreDesignation": "L1"
      }
    ],
    "category": {
      "code": "FARMER",
      "setAt": "2025-06-02T10:00:00+05:30",
      "frozen": true,
      "frozenReason": "LAND_AUTHENTICATED"
    },
    "status": {
      "lifeStatus": "ACTIVE"
    },
    "photo": {
      "fileId": "7a6b5c4d-0000-4000-8000-000000000225",
      "kind": "PHOTO_FARMER",
      "url": "https://files.example.invalid/urvi/signed/farmer-a.jpg",
      "mimeType": "image/jpeg"
    },
    "interestedInTrade": true,
    "nfCategory": "PMDS+C1",
    "endorsementStatus": "PENDING",
    "flags": {
      "hasAtm": true,
      "hasAGrade": false,
      "hasCompactBlock": true,
      "profileComplete": true
    }
  },
  "lands": [
    {
      "id": 810001,
      "clientId": "4a7d2b3f-0000-4000-8000-000000004097",
      "version": 3,
      "createdAt": "2025-06-02T10:05:00+05:30",
      "updatedAt": "2025-10-14T09:30:00+05:30",
      "active": true,
      "farmerId": 700001,
      "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
      "category": "LAND_OWNED",
      "landType": "IRRIGATED",
      "ownershipType": "OWNER",
      "khataNo": "KH-0001",
      "surveyNo": "SY-101/2",
      "acres": 2.5,
      "authenticated": true,
      "disabled": false,
      "leasedTo": [],
      "geofence": {
        "polygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                80.1001,
                16.5001
              ],
              [
                80.1012,
                16.5001
              ],
              [
                80.1012,
                16.501
              ],
              [
                80.1001,
                16.501
              ],
              [
                80.1001,
                16.5001
              ]
            ]
          ]
        },
        "captureMethod": "OSM_MOTION",
        "accuracyM": 4.5,
        "pointCount": 4,
        "capturedAt": "2025-10-14T09:30:00+05:30",
        "areaAcres": 2.4,
        "kmlUrl": "https://files.example.invalid/urvi/signed/land-1001.kml"
      },
      "checksum": "c1a5e0d7"
    }
  ],
  "livestock": [
    {
      "id": 820001,
      "clientId": "8e1b6f7d-0000-4000-8000-000000000001",
      "version": 1,
      "farmerId": 700001,
      "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
      "animalType": "ADULT_COW",
      "count": 2,
      "active": true
    }
  ],
  "cropStock": [
    {
      "id": 830001,
      "clientId": "8e1b6f7d-0000-4000-8000-000000000002",
      "version": 1,
      "farmerId": 700001,
      "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
      "productCode": "PADDY",
      "quantityQuintals": 12.5,
      "active": true
    }
  ],
  "cropBlocks": [
    {
      "id": 840001,
      "clientId": "5b8e3c4a-0000-4000-8000-000000008193",
      "version": 4,
      "createdAt": "2025-10-01T08:00:00+05:30",
      "updatedAt": "2025-10-14T09:30:00+05:30",
      "active": true,
      "farmerId": 700001,
      "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
      "landId": 810001,
      "landClientId": "4a7d2b3f-0000-4000-8000-000000004097",
      "landChecksum": "c1a5e0d7",
      "tileId": "TILE-840001",
      "planType": "SEASON_ACTUAL",
      "season": "2025-26",
      "month": "2025-10",
      "cropType": "AGRICULTURE",
      "crops": [
        {
          "clientId": "5b8e3c4a-0000-4000-8000-000000008449",
          "id": 841001,
          "productCode": "PADDY",
          "acres": 1.5,
          "isMajor": true,
          "seedVariety": "BPT-5204",
          "expectedHarvestDate": "2025-12-15",
          "harvestStatus": "NOT_STARTED",
          "placeholder": false
        },
        {
          "clientId": "5b8e3c4a-0000-4000-8000-000000008450",
          "id": 841002,
          "productCode": "RED_GRAM",
          "acres": 0.5,
          "isMajor": false,
          "harvestStatus": "NOT_STARTED",
          "placeholder": false
        }
      ],
      "practiceCodes": [
        "AP-GOV-KAP-100_PERCENT_CHEMICAL_FREE_NATURAL_FARMING",
        "AP-GOV-KAP-BEEJAMRUTHAM"
      ],
      "sowingDate": "2025-07-10",
      "photo": {
        "fileId": "7a6b5c4d-0000-4000-8000-000000000225",
        "kind": "PHOTO_CROP",
        "url": "https://files.example.invalid/urvi/signed/crop-840001.jpg"
      },
      "geofence": {
        "polygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                80.1001,
                16.5001
              ],
              [
                80.1012,
                16.5001
              ],
              [
                80.1012,
                16.501
              ],
              [
                80.1001,
                16.501
              ],
              [
                80.1001,
                16.5001
              ]
            ]
          ]
        },
        "captureMethod": "OSM_MOTION",
        "accuracyM": 4.5,
        "pointCount": 4,
        "capturedAt": "2025-10-14T09:30:00+05:30",
        "areaAcres": 2.4,
        "kmlUrl": "https://files.example.invalid/urvi/signed/land-1001.kml"
      },
      "changeLog": [],
      "compactBlockId": 860001,
      "editable": false,
      "totalAcres": 2
    }
  ],
  "farmingModels": [
    {
      "id": 850001,
      "clientId": "6c9f4d5b-0000-4000-8000-000000012289",
      "version": 2,
      "createdAt": "2025-08-01T09:00:00+05:30",
      "updatedAt": "2025-10-14T09:30:00+05:30",
      "active": true,
      "modelType": "ATM",
      "farmerId": 700001,
      "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
      "landId": 810001,
      "landClientId": "4a7d2b3f-0000-4000-8000-000000004097",
      "landChecksum": "c1a5e0d7",
      "tileId": "ATM-850001",
      "landAcres": 0.25,
      "raisedBeds": true,
      "vegetableCrops": [
        {
          "clientId": "6c9f4d5b-0000-4000-8000-000000012545",
          "productCode": "TOMATO",
          "lineType": "VEGETABLE",
          "harvestStatus": "PENDING"
        }
      ],
      "relayCropping": false,
      "maizeCultivation": true,
      "pulseCrops": [
        {
          "clientId": "6c9f4d5b-0000-4000-8000-000000012546",
          "productCode": "GREEN_GRAM",
          "lineType": "PULSE",
          "harvestStatus": "PENDING"
        }
      ],
      "practiceCodes": [
        "AP-GOV-KAP-BEEJAMRUTHAM"
      ],
      "incomeGeneration": true,
      "incomeGenerationDetails": 3500,
      "photo": {
        "fileId": "7a6b5c4d-0000-4000-8000-000000000225",
        "kind": "PHOTO_ATM",
        "url": "https://files.example.invalid/urvi/signed/atm-850001.jpg"
      },
      "harvestStatus": "PENDING"
    },
    {
      "id": 850002,
      "clientId": "6c9f4d5b-0000-4000-8000-000000012290",
      "version": 1,
      "modelType": "DKG_365",
      "farmerId": 700001,
      "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
      "month": "2025-10",
      "continuing": true,
      "active": true
    }
  ],
  "harvests": [],
  "plan": {
    "id": 870001,
    "clientId": "a03d8b9f-0000-4000-8000-000000000001",
    "version": 2,
    "updatedAt": "2025-10-14T09:30:00+05:30",
    "farmerId": 700001,
    "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
    "season": "2025-26",
    "status": "SUBMITTED",
    "lockedReason": null,
    "previousEndorsed": {
      "c1Acres": 2,
      "pmdsAcres": 0.5,
      "s2sAcres": 1,
      "aGradeAcres": 0,
      "s2sInCompactBlockAcres": 0.5,
      "desiCows": 2,
      "dkg": "SEASONAL",
      "atm": true
    },
    "previousCurrent": {
      "c1Acres": 2,
      "pmdsAcres": 0.5,
      "s2sAcres": 1,
      "aGradeAcres": 0,
      "s2sInCompactBlockAcres": 0.5,
      "desiCows": 2,
      "dkg": "SEASONAL",
      "atm": true
    },
    "current": {
      "c1Acres": 2.5,
      "pmdsAcres": 1,
      "s2sAcres": 1.5,
      "aGradeAcres": 0.5,
      "s2sInCompactBlockAcres": 1,
      "desiCows": 2,
      "dkg": "DKG_365",
      "atm": true
    },
    "pmdsPractisingYears": [
      "2022-23",
      "2023-24"
    ],
    "dgc": {
      "practising": true,
      "seasons": [
        "KHARIF",
        "RABI"
      ]
    },
    "totalLandExtentPrevious": 2.5,
    "totalLandExtentCurrent": 2.5,
    "submittedAt": "2025-10-14T09:30:00+05:30"
  },
  "metrics": {
    "ownedAcres": 2.5,
    "leasedInAcres": 0,
    "leasedOutAcres": 0.75,
    "cropActualAcres": 1.5,
    "atmAcres": 0.25,
    "usedAcres": 2.5,
    "availableAcres": 0,
    "kapSurveyCount": 1,
    "computedAt": "2025-10-14T09:30:00+05:30",
    "parcels": [
      {
        "landId": 810001,
        "landClientId": "4a7d2b3f-0000-4000-8000-000000004097",
        "surveyNo": "SY-101/2",
        "totalAcres": 2.5,
        "leasedOutAcres": 0.75,
        "cropActualAcres": 1.5,
        "atmAcres": 0.25,
        "availableAcres": 0,
        "disabled": false
      }
    ]
  },
  "endorsement": null
}
FieldTypeRequiredRulesMeaning
farmerFarmerYesFarmer (IE, Individual Entrepreneur).
landsLand[]No
livestockLivestock[]No
cropStockCropStock[]No
cropBlocksCropBlock[]No
farmingModelsFarmingModel[]No
harvestsHarvest[]No
planKapPlan | nullNo
metricsFarmerMetricsNoServer-side land usage, same formula as validation. All values in acres.
endorsementEndorsement | nullNo

304 Unchanged since the supplied ETag; use the cached copy.

400 Malformed request or schema violation.

Schema Problem.

Example 400 body
{
  "type": "https://urvi.example.invalid/problems/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "code": "VALIDATION_FAILED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "errors": [
    {
      "field": "/mobile",
      "code": "INVALID_MOBILE",
      "message": "Mobile must be 10 digits starting 6-9."
    }
  ]
}

401 Missing, invalid or expired access token. Refresh once, then ask the user to log in; pending outbox ops stay intact.

Schema Problem.

Example 401 body
{
  "type": "https://urvi.example.invalid/problems/token-expired",
  "title": "Session expired",
  "status": 401,
  "detail": "The access token has expired.",
  "code": "TOKEN_EXPIRED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

403 Authenticated but not allowed (role, tenant, device binding or feature switch).

Schema Problem.

Example 403 body
{
  "type": "https://urvi.example.invalid/problems/role-not-allowed",
  "title": "Not allowed",
  "status": 403,
  "detail": "Your role cannot perform this action.",
  "code": "ROLE_NOT_ALLOWED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

404 Resource not found or outside the user's work nodes.

Schema Problem.

Example 404 body
{
  "type": "https://urvi.example.invalid/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No such resource in your work area.",
  "code": "NOT_FOUND",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

426 App version below the minimum; block the UI with an update prompt. Pending outbox ops are kept.

Schema Problem.

Example 426 body
{
  "type": "https://urvi.example.invalid/problems/version-too-old",
  "title": "Update required",
  "status": 426,
  "detail": "Please update Urvi to continue.",
  "code": "VERSION_TOO_OLD",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "minAppVersion": "2.0.0"
}

429 Rate limited per device / user. Respect `Retry-After`.

Schema Problem.

Example 429 body
{
  "type": "https://urvi.example.invalid/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Slow down and retry later.",
  "code": "RATE_LIMITED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "retryAfterSeconds": 30
}

500 Unexpected server error; retry with backoff (writes are idempotent).

Schema Problem.

Example 500 body
{
  "type": "https://urvi.example.invalid/problems/internal-error",
  "title": "Server error",
  "status": 500,
  "detail": "Something went wrong. Please try again.",
  "code": "INTERNAL_ERROR",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}