KAP / annual action plan for a season
Operation
getFarmerPlan- Call
GET /gateway/urvi-app-service/api/v2/farmers/{farmerId}/plan- Group
- Planning (KAP)
- Features
- KAP / Annual Action Plan 2025-26, Farmer endorsement details, VO / SHG / Farmer endorsement
- Replaces today
Use case. Called online when KAP 25-26 opens (and read-only from the endorsement farmer list) to load the current-season plan with last season's endorsed and current values and the computed land extents. Submissions go through /sync/batch (kap_plan). status LOCKED with lockedReason tells the app to disable the form and show the endorsed banner.
Rules.
season=currentmaps to the KAP season in config.
Error codes. NOT_FOUND, CATEGORY_NOT_ALLOWED
Parameters
| Name | In | Type | Required | Meaning | Example |
|---|---|---|---|---|---|
X-App-Version | header | string | Yes | App version `major.minor.patch+build`. Too old -> 426 `VERSION_TOO_OLD`. · pattern ^\d+\.\d+\.\d+(\+\d+)?$ | 2.0.0+200 |
X-Device-Id | header | string (uuid) | Yes | App-scoped device UUID (not ANDROID_ID). | 6b1f2c3d-0000-4000-8000-00000000d001 |
X-Request-Id | header | string (uuid) | No | Client-generated request id for tracing; echoed in responses and problems. | 0e0c5a1b-0000-4000-8000-0000000000a1 |
Accept-Language | header | string | No | Language for messages and labels. · one of en, te, ta; default "en" | te |
X-Tenant | header | string | No | Tenant code; must match the token. Urvi: `ap.gov`. · one of ap.gov | ap.gov |
farmerId | path | string | Yes | Farmer 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 64 | 3f6c1a2e-0000-4000-8000-00000000f001 |
season | query | string | No | `current`, `previous` or an explicit season like `2025-26`; the server maps it to year-specific datasets. · pattern ^(current|previous|\d{4}-\d{2})$; default "current" | current |
Request
No body.
Responses
200 Plan.
Schema KapPlan.
{
"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"
}| Field | Type | Required | Rules | Meaning |
|---|---|---|---|---|
id | integer (int64) | No | server-set | Server id (assigned by the App Service). |
clientId | string (uuid) | Yes | Client-generated UUID (the app's `appId`/`aliasId`). Stable for the life of the entity and used for idempotent creates and parent references. | |
version | integer (int64) | No | ≥ 1; server-set | Monotonic server version; send as `baseVersion` on updates. |
createdAt | string (date-time) | No | server-set | |
updatedAt | string (date-time) | No | server-set | |
active | boolean | No | False once soft-deleted / disabled. | |
farmerId | integer (int64) | No | Server id (assigned by the App Service). | |
farmerClientId | string (uuid) | No | ||
season | string | Yes | pattern ^\d{4}-\d{2}$ | Season label, e.g. `2025-26`. |
status | string | No | one of NOT_STARTED, SUBMITTED, LOCKED; server-set | |
lockedReason | string | null | No | one of FARMER_ENDORSED, SHG_ENDORSED, VO_ENDORSED, ; server-set | |
previousEndorsed | KapSeasonValues | No | KAP values for one season. Ceilings -> `KAP_VALUE_EXCEEDS_LIMIT`. | |
previousCurrent | KapSeasonValues | No | KAP values for one season. Ceilings -> `KAP_VALUE_EXCEEDS_LIMIT`. | |
current | KapSeasonValues | Yes | KAP values for one season. Ceilings -> `KAP_VALUE_EXCEEDS_LIMIT`. | |
pmdsPractisingYears | string[] | No | At least one year before the previous season (`KAP_PMDS_YEARS_REQUIRED`). | |
dgc | object | No | If practising, >= 1 season (`KAP_DGC_SEASON_REQUIRED`). | |
totalLandExtentPrevious | number (double) | No | server-set | Unit: acres. |
totalLandExtentCurrent | number (double) | No | server-set | Unit: acres. |
submittedAt | string (date-time) | No | server-set |
400 Malformed request or schema violation.
Schema Problem.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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"
}