Plug your dispatch system into a field force that proves its work.

Keep your ERP, DMS or spreadsheet as the source of truth. Push work into Gigs4You with your own IDs; pull back GPS-verified proof, geofence results, photos and escrow payouts. Every write is idempotent — retry anything, duplicate nothing.

1. Authentication

Base URL: https://api.gigs4you.co.ke/api/v1. Create a dedicated manager user for your integration (Dashboard → Team users), then exchange its credentials for a bearer token. Access tokens are short-lived — refresh with POST /auth/refresh and body {"refreshToken": "…"}.

curl -X POST https://api.gigs4you.co.ke/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"dispatch@yourco.co.ke","password":"••••••••"}'

# → { "access_token": "eyJ…", "refresh_token": "…", "user": { … } }

Send it on every request as Authorization: Bearer <access_token>. All data is scoped to that user's organisation — you can never read or write another org's records. The full machine-readable reference lives at /docs (OpenAPI/Swagger) on the API host.

2. Idempotency — retry anything

Field networks drop. So does yours. Every mutating endpoint that matters accepts an Idempotency-Key header (8–128 chars, [A-Za-z0-9_-:.]):

• First request with a key runs normally; its response is stored for 72 hours.
• Any repeat with the same key and the same body returns the stored response (header Idempotent-Replayed: true) — nothing runs twice.
• Same key, different body → 422. Repeat while the first is still running → 409; back off and retry.
• A request that failed releases its key, so a retry after an error runs for real.

3. Push tasks — POST /enterprise/tasks/sync

Bulk upsert of up to 200 tasks per call, keyed by your externalRef (unique per organisation). Re-sending a batch is safe: refs already synced come back as existing.

curl -X POST https://api.gigs4you.co.ke/api/v1/enterprise/tasks/sync \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: route-2026-10-05-batch-01' \
  -d '{
  "tasks": [{
    "externalRef": "SAP-DLV-000123",
    "title": "Shelf audit — Naivas Westlands",
    "description": "Count facings for SKUs 1001-1040, photo every bay",
    "latitude": -1.2676, "longitude": 36.8108,
    "locationName": "Naivas Westlands",
    "geofenceRadiusMetres": 150,
    "dueAt": "2026-10-05T11:00:00.000Z",
    "agentId": "6f1c…",
    "paymentAmount": 450,
    "requiresPhoto": true,
    "checklist": [{ "label": "Photo of each bay", "required": true, "requiresPhoto": true, "requiredPhotoCount": 4 }]
  }]
}'

{ "created": 1, "existing": 0, "failed": 0,
  "results": [{ "externalRef": "SAP-DLV-000123", "status": "created", "taskId": "a3e9…" }] }

4. Pull status & proof — GET /enterprise/tasks/status?refs=A,B,C

Up to 200 refs per call. Poll on your own schedule (every 5–15 minutes is plenty), or skip polling and use webhooks.

[{
  "externalRef": "SAP-DLV-000123", "taskId": "a3e9…",
  "status": "completed", "acceptanceStatus": "accepted", "agentId": "6f1c…",
  "completedAt": "2026-10-05T09:12:44.000Z", "completedOffline": true,
  "geoVerified": true, "completionDistanceMetres": 38,
  "photoUrls": ["https://…/task-photos/…jpg"], "photoVerified": true,
  "approvedAt": "2026-10-05T09:13:02.000Z", "paymentAmount": "450.00"
}]

completedOffline: true means the agent captured the proof with no signal and the phone synced it later; completedAt is the real on-device capture time (trusted only within 10 minutes ahead and 7 days back).

5. Webhooks — get told, don’t poll

Register an HTTPS endpoint in the dashboard (Integrations, org admins) and pick the events you want. We POST each event to you the moment it happens, with your externalRef on tasks you pushed through the sync API.

POST https://erp.example.co.ke/hooks/gigs4you
G4Y-Event: task.completed
G4Y-Event-Id: 5b0e…          (same for every retry: de-duplicate on it)
G4Y-Signature: t=1760690000,v1=9c4f…

{ "id": "5b0e…", "type": "task.completed", "createdAt": "2026-10-17T08:33:20.000Z",
  "organisationId": "…",
  "data": { "taskId": "a3e9…", "externalRef": "SAP-DLV-000123", "status": "completed",
            "agentId": "6f1c…", "completedAt": "2026-10-17T08:33:18.000Z" } }

Verify every request. Compute HMAC-SHA256(secret, t + "." + rawBody) as hex and compare it with v1 in constant time; reject anything older than 5 minutes.

// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const ok = crypto.timingSafeEqual(
  Buffer.from(v1, 'hex'),
  crypto.createHmac('sha256', SECRET).update(`${t}.${rawBody}`).digest());
if (!ok || Date.now() / 1000 - Number(t) > 300) return res.status(400).end();

Delivery. Answer any 2xx within 10 seconds (queue the work, then reply). Anything else is retried at 1, 5, 15 and 60 minutes, then 3, 6, 10 and 10 hours: about 24 hours in all. After that the delivery is marked failed, and you can resend it from the dashboard. Delivery is at least once and can be out of order: use G4Y-Event-Id to de-duplicate, and read status rather than assuming order. Payloads carry ids and status only; fetch details from the status endpoint. Endpoints must be public https:// addresses.

6. Escrow — how money moves

Read it any time: GET /wallet/org (includes escrowBalance) and GET /wallet/org/escrow (records + an integrity check that escrowBalance equals the sum of locked escrows). Workers are never charged a fee at any step.

7. Geographic rules

• Latitude −90…90, longitude −180…180, both or neither, never (0,0) — enforced by the API and by database constraints.
• GPS pings with negative speed/accuracy are rejected; accuracy > 100 m or speed > 120 km/h is flagged for fraud review.
• Offline-buffered pings carry a device recordedAt and are ordered by it, so routes replay in the order they were walked.

8. Enterprise analytics

9. Errors

10. Plans

Task sync API and webhooks: Starter and above. Route optimisation and territory analytics: Growth and above. Tax compliance and predictive analytics: Scale and Enterprise. Core field operations — GPS proof, offline sync, escrow — are on every plan. See pricing →