API contracts / App Service v2 / Compact blocks

Tiles eligible for a compact block

OperationlistEligibleTiles
Call
GET /gateway/urvi-app-service/api/v2/compact-blocks/eligible-tiles
Group
Compact blocks
Features
Compact Block

Use case. Called online by the compact-block wizard after the user picks VOs and SHGs. The server applies the eligibility rules (current season, latest version per tile, geofence present, land with both survey and khata numbers, not in another active block, active farmer) and returns tiles grouped-ready by farmer with crop acres and the S2S flag. Offline the wizard uses the local equivalent.

Error codes. 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
voIdsqueryinteger (int64)[]YesVO ids. · min items 1; max items 2004101
shgIdsqueryinteger (int64)[]NoSHG ids; 0 = Non-SHG. · max items 50052001
excludeCompactBlockIdqueryinteger (int64)NoWhen editing: treat this block's own tiles as eligible.860001

Request

No body.

Responses

200 Eligible tiles.

Schema EligibleTilesResponse.

Example 200 body
{
  "season": "2025-26",
  "items": [
    {
      "cropBlockId": 840021,
      "tileId": "TILE-840021",
      "farmer": {
        "id": 700003,
        "clientId": "3f6c1a2e-0000-4000-8000-000000061443",
        "name": "Farmer C"
      },
      "landId": 810021,
      "surveyNo": "SY-120",
      "khataNo": "KH-0021",
      "acres": 2.75,
      "shg": {
        "id": 52001,
        "type": "SHG",
        "name": "SHG A",
        "code": "SHG-52001"
      },
      "vo": {
        "id": 4101,
        "type": "VO",
        "name": "VO A",
        "code": "VO-4101"
      },
      "hasGeofence": true,
      "isS2S": true,
      "cropCodes": [
        "PADDY"
      ]
    }
  ]
}
FieldTypeRequiredRulesMeaning
itemsEligibleTile[]Yes
seasonstringNopattern ^\d{4}-\d{2}$Season label, e.g. `2025-26`.

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

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