API contracts / App Service v2 / Compact blocks

Compact blocks for VOs

OperationlistCompactBlocks
Call
GET /gateway/urvi-app-service/api/v2/compact-blocks
Group
Compact blocks
Features
Compact Block, Data download (Unit / FMT)
Replaces today

Use case. Called by Unit / FMT data download (Compact Block item) and the Compact Block tab refresh. Returns active blocks of the given VOs with members, computed total acres and warning flags (BELOW_5_ACRES, INACTIVE_FARMER, NOT_FARMER, NOT_S2S). No hard-coded date cut-off. Writes go through /sync/batch.

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)[]NoVO ids; default all assigned VOs. · max items 2004101,4102
farmerIdsqueryinteger (int64)[]NoBlocks containing these farmers. · max items 200700001
cursorquerystringNoOpaque cursor from the previous page. · max length 512eyJwIjoyfQ
pageSizequeryintegerNoItems per page. · ≥ 1; ≤ 500; default 100100

Request

No body.

Responses

200 Compact blocks.

Schema CompactBlockPage.

Example 200 body
{
  "items": [
    {
      "id": 860001,
      "clientId": "7d0a5e6c-0000-4000-8000-000000016385",
      "version": 5,
      "updatedAt": "2025-10-14T09:30:00+05:30",
      "active": true,
      "name": "CB 1",
      "tileId": "CB-860001",
      "voIds": [
        4101
      ],
      "members": [
        {
          "id": 861001,
          "clientId": "7d0a5e6c-0000-4000-8000-000000016641",
          "compactBlockId": 860001,
          "cropBlockId": 840001,
          "cropBlockClientId": "5b8e3c4a-0000-4000-8000-000000008193",
          "tileId": "TILE-840001",
          "farmerId": 700001,
          "landId": 810001,
          "shg": {
            "id": 52001,
            "type": "SHG",
            "name": "SHG A",
            "code": "SHG-52001"
          },
          "vo": {
            "id": 4101,
            "type": "VO",
            "name": "VO A",
            "code": "VO-4101"
          },
          "acres": 2,
          "joinedAt": "2025-10-14T09:30:00+05:30",
          "active": true
        },
        {
          "id": 861002,
          "clientId": "7d0a5e6c-0000-4000-8000-000000016642",
          "compactBlockId": 860001,
          "cropBlockId": 840017,
          "tileId": "TILE-840017",
          "farmerId": 700002,
          "landId": 810017,
          "shg": {
            "id": 52001,
            "type": "SHG",
            "name": "SHG A",
            "code": "SHG-52001"
          },
          "vo": {
            "id": 4101,
            "type": "VO",
            "name": "VO A",
            "code": "VO-4101"
          },
          "acres": 3.25,
          "joinedAt": "2025-10-14T09:30:00+05:30",
          "active": true
        }
      ],
      "totalAcres": 5.25,
      "flags": []
    }
  ],
  "page": {
    "nextCursor": null,
    "hasMore": false,
    "pageSize": 100
  }
}
FieldTypeRequiredRulesMeaning
itemsCompactBlock[]Yes
pagePageInfoYes

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