API contracts / App Service v2 / Endorsements

Endorsement statuses (VO, SHG, farmer)

OperationlistEndorsements
Call
GET /gateway/urvi-app-service/api/v2/endorsements
Group
Endorsements
Features
Farmer endorsement details, VO / SHG / Farmer endorsement, Farmer list & search, Home and bottom bar
Replaces today

Use case. Called by the endorsement worker every 15 minutes while online, on Home pull-to-refresh, and by the VO tab (Unit). scope=me returns endorsements assigned to or made by the user; scope=vo returns the VO, its SHGs and farmers in one shape. Each row carries allowedActions so the menus (Raise flag, Mark as endorsed, comments, abstracts) come from the server state machine.

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
scopequerystringYes`me` or `vo`. · one of me, vovo
voIdqueryinteger (int64)NoRequired with `scope=vo`.4101
sincequerystring (date-time)NoOnly rows changed after this time.2025-10-14T09:30:00+05:30
cursorquerystringNoOpaque cursor from the previous page. · max length 512eyJwIjoyfQ
pageSizequeryintegerNoItems per page. · ≥ 1; ≤ 500; default 100100

Request

No body.

Responses

200 Endorsements.

Schema EndorsementPage.

Example 200 body
{
  "items": [
    {
      "id": 880001,
      "entityType": "SHG",
      "entityId": 52001,
      "entityCode": "SHG-52001",
      "name": "SHG A",
      "status": "FLAGGED",
      "vo": {
        "id": 4101,
        "type": "VO",
        "name": "VO A",
        "code": "VO-4101"
      },
      "shg": {
        "id": 52001,
        "type": "SHG",
        "name": "SHG A",
        "code": "SHG-52001"
      },
      "reviewedBy": {
        "userId": 9001,
        "displayName": "User A",
        "roleCode": "role.ap.gov.unit-incharge"
      },
      "reviewedAt": "2025-10-14T09:30:00+05:30",
      "allowedActions": [
        "ENDORSE",
        "NOT_RESOLVED"
      ],
      "commentCount": 2,
      "version": 3
    }
  ],
  "page": {
    "nextCursor": null,
    "hasMore": false,
    "pageSize": 100
  }
}
FieldTypeRequiredRulesMeaning
itemsEndorsement[]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"
}