iotoms Docs

Log a store visit outcome

POST
/api/v1/ops/routes/{routeVisitId}/log

Records a planned store visit as visited or skipped, with GPS coordinates; skipping needs a reason code. Only the salesperson who owns the open day can log it, each visit only once. Returns the updated route coverage percentage.

How to use it

  1. Get the visit ID (storeVisitId) from Get today's route; the visit must still be PENDING and belong to your open day.
  2. Send visitStatus VISITED or SKIPPED (with skipReasonCode), GPS coordinates, startOdometerKm and visitedAt.
  3. The visit is recorded and cannot be logged again; the response returns the updated coverage percentage.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

routeVisitId*string

ID of the planned store visit (storeVisitId) from Get today's route.

Formatuuid

Header Parameters

Request Body

application/json
  1. body
visitStatus*string

Outcome to record: VISITED or SKIPPED.

Value in"PENDING""VISITED""SKIPPED"
skipReasonCode?|

Required when visitStatus is SKIPPED: STORE_CLOSED, OWNER_UNAVAILABLE, CREDIT_LIMIT_REACHED, LOW_STOCK or OTHER.

Value in"STORE_CLOSED""OWNER_UNAVAILABLE""CREDIT_LIMIT_REACHED""LOW_STOCK""OTHER"null
notes?|

Optional free-text notes about the visit.

gpsLat*number

Latitude where the visit was logged, in decimal degrees. Required.

Formatdouble
gpsLon*number

Longitude where the visit was logged, in decimal degrees. Required.

Formatdouble
gpsAccuracyMeters?|

Optional GPS accuracy reported by the device, in metres.

Formatint32
startOdometerKm*integer

Vehicle odometer reading in km. Required and must be greater than 0; it is checked but not saved with the visit.

Formatint32
endOdometerKm?|

Optional closing odometer reading in km, 0 or more; it is checked but not saved with the visit.

Formatint32
visitedAt*string

When the visit happened (ISO 8601 date-time). Defaults to now.

Formatdate-time

Response Body

OK

*/*
  1. response
status*string

Outcome of the request: SUCCESS when it worked; errors return an error status with the reason in message.

message*string

Short human-readable message describing the outcome.

data?

The visit as logged, with the day's updated route coverage.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/ops/routes/497f6eca-6276-4993-bfeb-53cbbbba6f08/log' \  -H 'Content-Type: application/json' \  -d '{  "visitStatus": "PENDING",  "gpsLat": 0.1,  "gpsLon": 0.1,  "startOdometerKm": 0,  "visitedAt": "2019-08-24T14:15:22Z"}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "storeVisitId": "52169b4e-ab9f-4d60-adb2-503d32525cde",    "visitStatus": "PENDING",    "skipReasonCode": "STORE_CLOSED",    "notes": "string",    "visitedAt": "2019-08-24T14:15:22Z",    "coveragePercent": 0  }}