API contracts / App Service v2 / Sync

Status of an asynchronously processed batch

OperationgetSyncBatch
Call
GET /gateway/urvi-app-service/api/v2/sync/batches/{batchId}
Group
Sync
Features
Pending sync, Settings

Use case. Called by the sync worker after a 202 from /sync/batch, honouring Retry-After, until state is COMPLETED or FAILED; then the app handles result exactly like a 200 batch response. Also used by Pending Sync to show progress of a long batch.

Rules.

  • Batches are visible only to the user and device that sent them; results are kept 30 days.

Error codes. NOT_FOUND

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
batchIdpathstring (uuid)YesClient batch UUID.5d4c3b2a-0000-4000-8000-0000000000c1

Request

No body.

Responses

200 Batch status.

Schema SyncBatchStatus.

Example 200 body
{
  "batchId": "5d4c3b2a-0000-4000-8000-000000000193",
  "state": "COMPLETED",
  "receivedAt": "2025-10-14T09:30:00+05:30",
  "completedAt": "2025-10-14T09:31:02+05:30",
  "progress": {
    "total": 8,
    "processed": 8
  },
  "result": {
    "batchId": "5d4c3b2a-0000-4000-8000-000000000193",
    "processedAt": "2025-10-14T09:31:02+05:30",
    "changesCursor": "chg_eyJ2IjoxMjQwMH0",
    "results": [
      {
        "opId": "e0a1b2c3-0000-4000-8000-000000000001",
        "clientId": "3f6c1a2e-0000-4000-8000-000000061442",
        "entityType": "farmer",
        "status": "applied",
        "serverId": 700002,
        "serverVersion": 1,
        "error": null,
        "serverState": null
      },
      {
        "opId": "e0a1b2c3-0000-4000-8000-000000000002",
        "clientId": "4a7d2b3f-0000-4000-8000-000000004098",
        "entityType": "land",
        "status": "applied",
        "serverId": 810002,
        "serverVersion": 1,
        "error": null,
        "serverState": null
      },
      {
        "opId": "e0a1b2c3-0000-4000-8000-000000000003",
        "clientId": "5b8e3c4a-0000-4000-8000-000000008193",
        "entityType": "crop_block",
        "status": "rejected",
        "serverId": 840001,
        "serverVersion": 5,
        "error": {
          "type": "https://urvi.example.invalid/problems/part-of-compact-block",
          "title": "Part of a compact block",
          "status": 422,
          "detail": "This crop block is part of compact block CB 1 and cannot be edited.",
          "code": "PART_OF_COMPACT_BLOCK",
          "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
          "instance": "/sync/batch#ops/2"
        },
        "serverState": {
          "id": 840001,
          "clientId": "5b8e3c4a-0000-4000-8000-000000008193",
          "version": 5,
          "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
        }
      },
      {
        "opId": "e0a1b2c3-0000-4000-8000-000000000004",
        "clientId": "9f2c7a8e-0000-4000-8000-000000000001",
        "entityType": "crop_harvest",
        "status": "duplicate",
        "serverId": 940001,
        "serverVersion": 1,
        "error": null,
        "serverState": null
      },
      {
        "opId": "e0a1b2c3-0000-4000-8000-000000000005",
        "clientId": "a03d8b9f-0000-4000-8000-000000000001",
        "entityType": "kap_plan",
        "status": "applied",
        "serverId": 870001,
        "serverVersion": 3,
        "error": null,
        "serverState": null
      },
      {
        "opId": "e0a1b2c3-0000-4000-8000-000000000006",
        "clientId": "7d0a5e6c-0000-4000-8000-000000016642",
        "entityType": "compact_block_member",
        "status": "applied",
        "serverId": 861002,
        "serverVersion": 2,
        "error": null,
        "serverState": null
      },
      {
        "opId": "e0a1b2c3-0000-4000-8000-000000000007",
        "clientId": "b14e9caf-0000-4000-8000-000000000001",
        "entityType": "endorsement_action",
        "status": "rejected",
        "serverId": null,
        "serverVersion": null,
        "error": {
          "type": "https://urvi.example.invalid/problems/endorsement-kap-not-submitted",
          "title": "KAP not submitted",
          "status": 422,
          "detail": "Submit KAP before endorsing this farmer.",
          "code": "ENDORSEMENT_KAP_NOT_SUBMITTED",
          "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
          "instance": "/sync/batch#ops/6"
        },
        "serverState": null
      },
      {
        "opId": "e0a1b2c3-0000-4000-8000-000000000008",
        "clientId": "6c9f4d5b-0000-4000-8000-000000012291",
        "entityType": "farming_model",
        "status": "applied",
        "serverId": 850003,
        "serverVersion": 1,
        "error": null,
        "serverState": null
      }
    ],
    "idMap": [
      {
        "entityType": "farmer",
        "clientId": "3f6c1a2e-0000-4000-8000-000000061442",
        "serverId": 700002
      },
      {
        "entityType": "land",
        "clientId": "4a7d2b3f-0000-4000-8000-000000004098",
        "serverId": 810002
      },
      {
        "entityType": "kap_plan",
        "clientId": "a03d8b9f-0000-4000-8000-000000000001",
        "serverId": 870001
      },
      {
        "entityType": "farming_model",
        "clientId": "6c9f4d5b-0000-4000-8000-000000012291",
        "serverId": 850003
      }
    ]
  }
}
FieldTypeRequiredRulesMeaning
batchIdstring (uuid)Yes
statestringYesone of QUEUED, PROCESSING, COMPLETED, FAILED
receivedAtstring (date-time)No
completedAtstring (date-time)No
progressobjectNo
resultSyncBatchResult | nullNo

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

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