Attendance & Tracking API

Export monthly attendance grids, one employee's punches and hours, GPS travel summaries with travel allowance, live GPS trails and the location log, beat plans, and the login activity log.

7 endpointsBase URL https://api.spirestock.com/api/v1

Every request needs an API key or a session token. Last updated .

On this page (7)

GEThttps://api.spirestock.com/api/v1/reports/attendance/monthly

Monthly attendance grid: one row per employee with a status per day (P, A, a leave alias such as CL, or the holiday name), in/out times, days present/absent and percentage. In the current month the grid stops at today (IST). month, days and overall_percentage are top-level keys.

Access: API key read scope; staff need Monthly Attendance Report (48) — list.

Parameters

monthstring
YYYY-MM. Default: the current IST month
user_idnumber
One employee
Example request
curl "https://api.spirestock.com/api/v1/reports/attendance/monthly?month=2024-05" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "id": 51674,
      "first_name": "Sample",
      "middle_name": "",
      "last_name": "User",
      "role_name": "Sales Executive",
      "emp_sap_id": "EMP-003",
      "department_name": "Sales and Marketing ",
      "father_name": "Sample User G",
      "date_of_joining": "2024-05-22",
      "days_present": 7,
      "days_absent": 24,
      "working_days": 31,
      "percentage": 22.58,
      "days": [
        {
          "date": "2024-05-01",
          "status": "A",
          "in_time": "",
          "out_time": ""
        },
        {
          "date": "2024-05-02",
          "status": "A",
          "in_time": "",
          "out_time": ""
        }
      ]
    }
  ],
  "month": "2024-05",
  "days_in_month": 31,
  "days": [
    "2024-05-01"
  ],
  "leave_aliases": [
    "CL"
  ],
  "overall_percentage": 73.37
}

GEThttps://api.spirestock.com/api/v1/reports/attendance/monthly/staff/{userId}

One employee's month: punch in/out times and locations, working hours (H:MM) and km travelled per day.

Access: API key read scope; staff need any report sub-module (the /reports/* catch-all) — list.

Parameters

userIdnumberrequired
Employee id
monthstring
YYYY-MM. Default: the current IST month
Example request
curl "https://api.spirestock.com/api/v1/reports/attendance/monthly/staff/51674?month=2024-05" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "user": {
    "id": 51674,
    "first_name": "Sample",
    "middle_name": "",
    "last_name": "User",
    "emp_sap_id": "EMP-003",
    "role_name": "Sales Executive",
    "profile_image": null,
    "name": "Sample User Z"
  },
  "month": "2024-05",
  "from": "2024-05-01",
  "to": "2024-05-31",
  "data": [
    {
      "date": "2024-05-24",
      "id": 51674,
      "name": "Sample User AA",
      "role_name": "Sales Executive",
      "emp_sap_id": "EMP-003",
      "profile_image": null,
      "dis_sap_id": "EMP-003",
      "store_name": null,
      "store_image": null,
      "start_time": "20:53:55",
      "start_latitude": "20.0",
      "start_longitude": "78.0",
      "end_time": "20:54:34",
      "end_latitude": "20.0",
      "end_longitude": "78.0",
      "attendance_type": 1,
      "auto_logout": false,
      "working_hours": "0:00",
      "distance_travelled": 0,
      "added_employee_count": 0,
      "tagged_employee_count": 0
    }
  ]
}

GEThttps://api.spirestock.com/api/v1/tracking/travel-summary

Distance travelled from GPS fixes (accuracy 50 m or better) with the per-km charge and total. time_period 1 is daily (one row per employee); 2 is monthly (one row per employee, or per day with user_id). Without time_period the legacy summary is returned.

Access: API key read scope; staff need User Travel Summary (49) — list.

Parameters

time_periodstring
1 daily, 2 monthly
travel_datestring
Daily: YYYY-MM-DD or dd/mm/yyyy. Default: today in IST
monthstring
Monthly: YYYY-MM or mm/yyyy
user_idnumber
One employee
Example request
curl "https://api.spirestock.com/api/v1/tracking/travel-summary?time_period=1&travel_date=2024-06-10" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "user_id": 41997,
      "user_name": "Sample User C",
      "emp_sap_id": "EMP-007",
      "reporting_to_name": "Sample User X",
      "month_date": "2024-06-10",
      "distance_travelled": 6.3,
      "charges": 3.5,
      "total_charges": 22.05
    }
  ],
  "meta": {
    "time_period": 1,
    "date": "2024-06-10",
    "is_user": 0,
    "totals": {
      "distance_travelled": 1486.4,
      "total_charges": 5202.39
    }
  }
}

GEThttps://api.spirestock.com/api/v1/reports/login-activity

Sign-ins (web and mobile) by IST day, newest first. Names and roles come from the current profile. The old 5,000-row cap is gone; page through the range instead.

Access: API key read scope; staff need Log In Activity Log Report (53) — list.

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

date_fromstring
YYYY-MM-DD. Default: today in IST
date_tostring
Default: date_from
role_idnumber
Role
platformstring
web or mobile
searchstring
Case-insensitive contains on the user's full name, SAP id or role name; max 100 characters, % and _ match literally
pagenumber
Page number; junk or a value below 1 reads as 1 Default 1.
limitnumber
Page size, default 50, max 100 (larger values are clamped)
Example request
curl https://api.spirestock.com/api/v1/reports/login-activity \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "user_id": 51896,
      "emp_sap_id": "EMP-001",
      "user_name": "Sample User A",
      "role_id": 0,
      "role_name": "CTO",
      "platform": "web",
      "login_at": "2026-10-22T08:43:54.592Z"
    }
  ],
  "pagination": {
    "total": 17,
    "page": 1,
    "limit": 2,
    "total_pages": 9
  }
}

GEThttps://api.spirestock.com/api/v1/tracking/live/{userId}

One rep's last known position (current, or null when the rep has never pinged; user_name only comes with a position) and the GPS trail of one IST day, oldest point first. The trail is cursor-paged: pass trail_pagination.next_cursor back as cursor until has_more is false; total counts the whole day. Without limit a page holds 1,000 points; an explicit limit is clamped to 100. Non-managers can only read their own id. With live tracking switched off for the workspace, today (or no date) answers { user_id, current: null, trail: [], live_tracking_enabled: false }; a past date still returns its trail and trail_pagination, with current null, no user_name and live_tracking_enabled: false.

Access: API key read scope; staff need User Tracking (5) — list.

Cursor pagedFollow next_cursor until has_more is false. How pagination works

Parameters

userIdnumberrequired
Employee user id
datestring
IST day to replay, YYYY-MM-DD or dd/mm/yyyy. Default: today
limitnumber
Points per page. Default 1,000; an explicit value is clamped to 1-100
cursorstring
next_cursor from the previous page
Example request
curl "https://api.spirestock.com/api/v1/tracking/live/44955?date=2024-05-17&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": {
    "user_id": 44955,
    "user_name": "Sample User A",
    "current": {
      "latitude": "12.9716000",
      "longitude": "77.5946000",
      "speed": null,
      "heading": null,
      "battery": 77,
      "last_ping_at": "2024-05-17T17:29:43.000Z",
      "status": "offline"
    },
    "trail": [
      {
        "id": 1400115,
        "latitude": "12.9716000",
        "longitude": "77.5946000",
        "distance_travelled": 0,
        "created_at": "2024-05-17T00:30:46.000Z"
      },
      {
        "id": 1400116,
        "latitude": "12.9716000",
        "longitude": "77.5946000",
        "distance_travelled": 0,
        "created_at": "2024-05-17T00:30:47.000Z"
      }
    ],
    "trail_pagination": {
      "total": 3904,
      "limit": 2,
      "has_more": true,
      "next_cursor": "WyIyMDI0LTA1LTE3VDAwOjMwOjQ3LjAwMFoiLDE0MDAxMTZd"
    }
  }
}

GEThttps://api.spirestock.com/api/v1/tracking/location-log

Raw GPS fixes with the employee's name and SAP id, oldest first, cursor-paged on (created_at, id): pass pagination.next_cursor back as cursor with the same filters until has_more is false. No date means today (IST). Without limit a page holds 500 points; an explicit limit is clamped to 100. Cached 15 seconds.

Access: API key read scope; staff need User Tracking (5) — list.

Cursor pagedFollow next_cursor until has_more is false. How pagination works

Parameters

user_idnumber
One employee
datestring
One IST day, YYYY-MM-DD or dd/mm/yyyy
from_datestring
Range start (IST day)
to_datestring
Range end (inclusive)
limitnumber
Points per page. Default 500; an explicit value is clamped to 1-100
cursorstring
next_cursor from the previous page
Example request
curl "https://api.spirestock.com/api/v1/tracking/location-log?user_id=44955&date=2024-05-17&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "id": 1400115,
      "organization_id": 6,
      "user_id": 44955,
      "latitude": "12.9716000",
      "longitude": "77.5946000",
      "distance_travelled": 0,
      "velocity": null,
      "travel_charges": "3.50",
      "accuracy": null,
      "sync_date_time": null,
      "flag": 0,
      "status": null,
      "message": null,
      "createdAt": "2024-05-17T00:30:46.000Z",
      "updatedAt": "2024-05-17T00:30:46.000Z",
      "sp_user": {
        "first_name": "Sample",
        "last_name": "User A",
        "official_email": "[email protected]",
        "emp_sap_id": "EMP-001"
      },
      "user_name": "Sample User A",
      "employee_name": "Sample User A",
      "emp_sap_id": "EMP-001"
    }
  ],
  "pagination": {
    "total": 3904,
    "limit": 2,
    "has_more": true,
    "next_cursor": "WyIyMDI0LTA1LTE3VDAwOjMwOjQ3LjAwMFoiLDE0MDAxMTZd",
    "date_from": "2024-05-17",
    "date_to": "2024-05-17"
  }
}

GEThttps://api.spirestock.com/api/v1/beat-plans

Planned market visits per sales rep and day, newest plan_date first. Staff tokens only ever see their own plans. Dates are YYYY-MM-DD; other values are ignored. outlets is a JSON string. Cached 60 seconds.

Access: API key read scope; any staff user, for their own records.

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

user_idnumber
Sales rep
datestring
One day, YYYY-MM-DD (overrides the range)
date_fromstring
Range start, YYYY-MM-DD
date_tostring
Range end (inclusive), YYYY-MM-DD
statusnumber
1 planned, 2 in progress, 3 completed
searchstring
Case-insensitive contains on rep name or route name; max 100 characters, % and _ match literally
pagenumber
Page number; junk or a value below 1 reads as 1 Default 1.
limitnumber
Page size, default 20, max 100 (larger values are clamped)
Example request
curl "https://api.spirestock.com/api/v1/beat-plans?date_from=2024-05-01&date_to=2024-05-31" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "id": 92,
      "organization_id": 6,
      "user_id": 44923,
      "user_name": "Sample User A",
      "plan_date": "2024-05-20",
      "route_id": 78,
      "route_name": "Route A",
      "outlets": "[]",
      "total_outlets": 0,
      "visited_outlets": 0,
      "status": 1,
      "notes": "Cover the market lane first",
      "createdAt": "2026-10-22T08:50:32.979Z",
      "updatedAt": "2026-10-22T08:50:32.979Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 2,
    "total_pages": 1
  }
}