> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Report

> Create a new report.

You can create reports programmatically via an API request. Reports are generated based on specified date ranges, members, and places.

### REQUEST

```shell theme={null}
POST https://api.hellotracks.com/api/createreport

{
	data: {
		day: 20210428,
		accounts: ["<member-username-or-uid-or-place-uid>"],
		format: "xlsx",
		reporttype: "jobs",
		columns: [
			{"key": "member"},
			{"key": "title"},
			{"key": "status"}
		]
	}
}
```

**reporttype** `string` *required*

Type of report to generate. See [Report Types](#report-types) section below for available options.

**format** `string`

Output format for the report. Available formats depend on report type:

* `xlsx` - Excel spreadsheet (most reports)
* `csv` - Comma-separated values (most reports)
* `pdf` - PDF document (most reports)
* `geojson` - GeoJSON format (location-based reports)
* `zip` - Compressed archive (GPX tracks, time allocation)

**day** `number`

Single day for the report in YYYYMMDD format (e.g., 20210428). Use this OR the `from`/`until` parameters.

**from** `integer`

Start day for the report in YYYYMMDD format. Use with `until` instead of `day` for multi-day reports.

**until** `integer`

End day for the report in YYYYMMDD format. Use with `from` instead of `day` for multi-day reports.

**accounts** `array` *required*

Array of member usernames or UIDs or array of place UIDs to include in the report. Required for most report types.

**columns** `array`

Optional array of column configurations to customize report output. Each column object can contain:

* `key` (string, required): Column identifier (see report-specific columns below)
* `rename` (string, optional): Custom column name in output

If omitted, report uses default columns.

**async** `boolean` (default: false)

Make the report in the background. The answer comes right away with a report job instead of the file; see [Large reports](#large-reports).

## Report Types

### Job Reports

#### `jobs` - Jobs Report

Complete job information across multiple days.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Up to 10,000 days
* **Requires:** `accounts` (members)
* **Available Columns:** member, date, title, status, status\_ts, status\_response, address, place, contact\_name, contact\_phone, teams, orderid, type, scheduled\_window, check\_ins, check\_outs, onsite, priority, created, saved, accepted, pickup\_items, dropoff\_items, manual\_checks, notes, latitude, longitude, comments, signature, signature\_name, signature\_date, attachments, custom\_fields, form\_fields, public\_url

#### `dayroute` - Day Route Report

Single-day route with sequence and routing information.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Single day only
* **Requires:** `accounts` (members)
* **Available Columns:** number, member, date, title, status, status\_ts, status\_response, routeinfo, address, place, contact\_name, contact\_phone, teams, orderid, type, scheduled\_window, check\_ins, check\_outs, onsite, priority, created, saved, accepted, pickup\_items, dropoff\_items, manual\_checks, notes, latitude, longitude, signature, attachments, custom\_fields, form\_fields, public\_url

### Activity & Location Reports

#### `activities` - Activities Report

Member activity log and events.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Up to 30 days
* **Requires:** `accounts` (members)

#### `checkins` - Check-ins Report

Place and job check-in records.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Up to 10,000 days
* **Requires:** `accounts` (members)

#### `gpx` - GPX Tracks Export

GPS track data in GPX format (compressed).

* **Formats:** zip (containing .gpx files)
* **Date Range:** Up to 120 days
* **Requires:** `accounts` (members)

### Time & Attendance Reports

#### `timesheet` - Timesheet Report

Working hours and time tracking.

* **Formats:** xlsx, pdf
* **Date Range:** Up to 120 days
* **Requires:** `accounts` (members)

#### `timeline` - Timeline Report

Chronological activity timeline.

* **Formats:** xlsx, csv
* **Date Range:** Up to 14 days
* **Requires:** `accounts` (members)

#### `worksheet` - Worksheet Report

Daily work summary.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Up to 14 days
* **Requires:** `accounts` (members)

#### `timeallocation` - Time Allocation Report

Time spent on different activities.

* **Formats:** xlsx, pdf, zip
* **Date Range:** Up to 14 days
* **Requires:** `accounts` (members)

### On-Site & Stop Reports

#### `placeonsite` - Place On-Site Report

Time spent at each place/location.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Up to 10,000 days
* **Requires:** place UIDs in `accounts`

#### `memberonsite` - Member On-Site Report

Member time spent at locations.

* **Formats:** xlsx, pdf
* **Date Range:** Up to 120 days
* **Requires:** `accounts` (members)

#### `stopsreport` - Stops Report

All stop locations with duration.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Up to 120 days
* **Requires:** `accounts` (members)

### Distance & Mileage Reports

#### `mileage` - Mileage Report

Distance tracking and trip details.

* **Formats:** xlsx
* **Date Range:** Up to 10,000 days
* **Requires:** `accounts` (members)
* **Available Columns:** date, member, start, end, distance, duration, minutes, maxspeed, avgspeed, from, to, purpose, comment, approvalstatus, approvedby, placesheet

### Alerts & Statistics

#### `alerts` - Alerts Report

Alert events and notifications.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Up to 10,000 days
* **Requires:** None (company-wide)

#### `statistics` - Statistics Report

Performance metrics and KPIs.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Up to 10,000 days
* **Requires:** `accounts` (members)
* **Available Columns:** member, distance, speed, maxspeed, tracks, jobs, ontime, delays, success, issues, engagement, totalJobOnsite, avgJobOnsite, totalPlaceOnsiteTime, avgPlaceOnsiteTime, totalPauseTime, avgPauseTime, totalTravelTime, avgTravelTime, totalTimeBetweenJobs, avgTimeBetweenJobs

### Directory Reports

#### `members` - Members Report

Member/user directory information.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Current data (no date filter)
* **Requires:** `accounts` (members)

#### `places` - Places Report

Places/locations directory.

* **Formats:** xlsx, csv, pdf, geojson
* **Date Range:** Current data (no date filter)
* **Requires:** place UIDs in `accounts`

### RESPONSE

If the request is successful, the response output can be saved as the content of the specified format file.

**Success Response:**

* For structured formats (xlsx, csv, pdf): Binary file content
* For geojson: JSON structure with GeoJSON features
* For zip: Compressed archive binary

**Error Response:**

```json theme={null}
{
  "status": <error_code>,
  "errorMsg": "Error message description"
}
```

### Large reports

Reports over many members or days can take longer than a request may last. Send them with `"async": true`. The answer is a report job:

```json theme={null}
{
  "status": 0,
  "job": { "id": "<report_job_id>", "status": "queued", "reportType": "jobs", "format": "xlsx" }
}
```

Then ask for the job with `/loadreportjob` until its `status` is `completed` or `failed`, for example every 5 seconds:

```bash theme={null}
curl -X POST https://api.hellotracks.com/api/loadreportjob \
  --header 'API-Key: YOUR_KEY_ID.YOUR_SECRET' \
  --header 'Content-Type: application/json' \
  -d '{ "data": { "jobId": "<report_job_id>" } }'
```

The job's `status` goes from `queued` to `processing`, then `completed` or `failed`:

* `completed`: `link` is the download link of the file; `filename`, `contentType` and `bytes` describe it.
* `failed`: `errorCode` and `errorMessage` say why.

A job id that isn't your company's answers status `-5`.

### Example Usage

```bash Jobs Report Example theme={null}
curl -X POST https://api.hellotracks.com/api/createreport \
--header 'API-Key: ...' -d \
'{
  "data": {
    "from": 20210428,
    "until": 20210430,
    "accounts": ["john@example.com", "jane@example.com"],
    "format": "xlsx",
    "reporttype": "jobs",
    "columns": [
      {"key": "member"},
      {"key": "title"},
      {"key": "status"},
      {"key": "address"}
    ]
  }
}' > jobs-report.xlsx
```

```bash Mileage Report Example theme={null}
curl -X POST https://api.hellotracks.com/api/createreport \
--header 'API-Key: ...' -d \
'{
  "data": {
    "day": 20231215,
    "accounts": ["driver1@example.com"],
    "format": "xlsx",
    "reporttype": "mileage",
    "columns": [
      {"key": "date"},
      {"key": "distance"},
      {"key": "from"},
      {"key": "to"}
    ]
  }
}' > mileage-report.xlsx
```

### Notes

* Maximum date ranges vary by report type to ensure performance
* Place-based reports need place UIDs in `accounts`
* Column customization is optional; reports use sensible defaults
* Binary formats (xlsx, pdf, zip) should be saved directly to files
* GeoJSON format is useful for mapping and GIS applications


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.