API contracts / App Service v2 / Farmers

Cursor-paged hydrated farmer snapshot

OperationgetFarmerSnapshot
Call
GET /gateway/urvi-app-service/api/v2/farmers/snapshot
Group
Farmers
Features
Data download (Cadre), Data download (Unit / FMT), Farmer list & search, Farmer hub (option tiles), Add/Edit farmer (IE profile), Farmer category (Farmer/C4/C5), Land assets, Leased land, Geofencing, Livestock, Crop stock (inventory), 365 DKG kitchen garden, ATM model (Anytime Money plot), ATM harvest, Crop Actual (portfolio), Crop Actual harvest, PMDS and A Grade crop details, KAP / Annual Action Plan 2025-26, Compact Block, Home and bottom bar
Replaces today

Use case. Called by Data download (Cadre: the selected VO; Unit / FMT: every assigned VO) and by Settings > Load more data. Each page holds fully hydrated farmers: profile, roles, land with geofences, livestock, crop stock, current-season Crop Actual blocks, farming models (ATM, DKG), harvests, KAP plan, land metrics and endorsement status, with attachment URLs (never bytes). The app writes each page in one transaction and stores the cursor in sync_checkpoint, so an interrupted download resumes from the failed page (replaces PARTIAL_SUCCESS bookkeeping). The last page returns deltaCursor for /farmers/changes.

Rules.

  • scope must be one of the user's work nodes (vo:<id>, unit for every assigned VO, self for the user's own record).
  • Zero farmers -> 200 with empty items and totalCount 0 (the app shows "No farmers found").
  • With featureSwitches.currentMonthPortfolioOnly, only Crop Actual blocks of the current and previous month are included.
  • Pages are consistent: the snapshot is taken at the first page; changes after it arrive through /farmers/changes from deltaCursor.

Error codes. NOT_FOUND, CURSOR_EXPIRED, ROLE_NOT_ALLOWED

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
scopequerystringYesWork-node scope: `vo:<id>`, `unit` or `self`. · pattern ^(vo:\d+|unit|self)$vo:4101
cursorquerystringNoOpaque cursor from the previous page. · max length 512eyJwIjoyfQ
pageSizequeryintegerNoItems per page. · ≥ 1; ≤ 500; default 100100

Request

No body.

Responses

200 Snapshot page.

Schema SnapshotPage.

Example 200 body
{
  "scope": "vo:4101",
  "items": [
    {
      "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
    }
  ],
  "page": {
    "nextCursor": null,
    "hasMore": false,
    "pageSize": 150
  },
  "totalCount": 1,
  "deltaCursor": "chg_eyJ2IjoxMjM0NX0",
  "generatedAt": "2025-10-14T09:30:00+05:30"
}
FieldTypeRequiredRulesMeaning
scopestringYesWork node the snapshot covers, e.g. `vo:4101`.
itemsFarmerAggregate[]Yes
pagePageInfoYes
totalCountintegerNo≥ 0
deltaCursorstring | nullNoOnly on the last page: start cursor for `/farmers/changes`.
generatedAtstring (date-time)No

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"
}

410 Cursor expired; download a fresh snapshot.

Schema Problem.

Example 410 body
{
  "type": "https://urvi.example.invalid/problems/cursor-expired",
  "title": "Cursor expired",
  "status": 410,
  "detail": "The change cursor is older than the retention window. Download a new snapshot.",
  "code": "CURSOR_EXPIRED",
  "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"
}