---
title: "Attendance & Tracking API — SpireStock REST API"
description: "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."
source: https://developers.spirestock.com/api-reference/attendance
---

# 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.

Base URL: `https://api.spirestock.com/api/v1`. Every request needs an API key (`X-API-Key`) or a session token (`Authorization: Bearer`); see https://developers.spirestock.com/api-reference/auth.

## Endpoints

- [GET /reports/attendance/monthly](https://developers.spirestock.com/api-reference/attendance#get-reports-attendance-monthly)
- [GET /reports/attendance/monthly/staff/{userId}](https://developers.spirestock.com/api-reference/attendance#get-reports-attendance-monthly-staff-userId)
- [GET /tracking/travel-summary](https://developers.spirestock.com/api-reference/attendance#get-tracking-travel-summary)
- [GET /reports/login-activity](https://developers.spirestock.com/api-reference/attendance#get-reports-login-activity)
- [GET /tracking/live/{userId}](https://developers.spirestock.com/api-reference/attendance#get-tracking-live-userId)
- [GET /tracking/location-log](https://developers.spirestock.com/api-reference/attendance#get-tracking-location-log)
- [GET /beat-plans](https://developers.spirestock.com/api-reference/attendance#get-beat-plans)

## GET /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | string | no | YYYY-MM. Default: the current IST month |
| `user_id` | number | no | One employee |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/attendance/monthly?month=2024-05" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "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
}
```

## GET /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | number | yes | Employee id |
| `month` | string | no | YYYY-MM. Default: the current IST month |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/attendance/monthly/staff/51674?month=2024-05" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "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
    }
  ]
}
```

## GET /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `time_period` | string | no | 1 daily, 2 monthly |
| `travel_date` | string | no | Daily: YYYY-MM-DD or dd/mm/yyyy. Default: today in IST |
| `month` | string | no | Monthly: YYYY-MM or mm/yyyy |
| `user_id` | number | no | One employee |

**Example request**

```bash
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**

```json
{
  "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
    }
  }
}
```

## GET /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.

Paged (page and limit): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | YYYY-MM-DD. Default: today in IST |
| `date_to` | string | no | Default: date_from |
| `role_id` | number | no | Role |
| `platform` | string | no | web or mobile |
| `search` | string | no | Case-insensitive contains on the user's full name, SAP id or role name; max 100 characters, % and _ match literally |
| `page` | number | no | Page number; junk or a value below 1 reads as 1 (default 1) |
| `limit` | number | no | Page size, default 50, max 100 (larger values are clamped) (default 50) |

**Example request**

```bash
curl https://api.spirestock.com/api/v1/reports/login-activity \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "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
  }
}
```

## GET /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.

Paged (cursor): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | number | yes | Employee user id |
| `date` | string | no | IST day to replay, YYYY-MM-DD or dd/mm/yyyy. Default: today |
| `limit` | number | no | Points per page. Default 1,000; an explicit value is clamped to 1-100 |
| `cursor` | string | no | next_cursor from the previous page |

**Example request**

```bash
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**

```json
{
  "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"
    }
  }
}
```

## GET /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.

Paged (cursor): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | number | no | One employee |
| `date` | string | no | One IST day, YYYY-MM-DD or dd/mm/yyyy |
| `from_date` | string | no | Range start (IST day) |
| `to_date` | string | no | Range end (inclusive) |
| `limit` | number | no | Points per page. Default 500; an explicit value is clamped to 1-100 |
| `cursor` | string | no | next_cursor from the previous page |

**Example request**

```bash
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**

```json
{
  "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": "user1@example.com",
        "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"
  }
}
```

## GET /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.

Paged (page and limit): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | number | no | Sales rep |
| `date` | string | no | One day, YYYY-MM-DD (overrides the range) |
| `date_from` | string | no | Range start, YYYY-MM-DD |
| `date_to` | string | no | Range end (inclusive), YYYY-MM-DD |
| `status` | number | no | 1 planned, 2 in progress, 3 completed |
| `search` | string | no | Case-insensitive contains on rep name or route name; max 100 characters, % and _ match literally |
| `page` | number | no | Page number; junk or a value below 1 reads as 1 (default 1) |
| `limit` | number | no | Page size, default 20, max 100 (larger values are clamped) (default 20) |

**Example request**

```bash
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**

```json
{
  "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
  }
}
```
