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

<ParamField body="reporttype" type="string" required>
  Type of report to generate. See [Report Types](#report-types) section below for available options.
</ParamField>

<ParamField body="format" type="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)
</ParamField>

<ParamField body="day" type="number">
  Single day for the report in YYYYMMDD format (e.g., 20210428). Use this OR the `from`/`until` parameters.
</ParamField>

<ParamField body="from" type="integer">
  Start day for the report in YYYYMMDD format. Use with `until` instead of `day` for multi-day reports.
</ParamField>

<ParamField body="until" type="integer">
  End day for the report in YYYYMMDD format. Use with `from` instead of `day` for multi-day reports.
</ParamField>

<ParamField body="accounts" type="array" required>
  Array of member usernames or UIDs or array of place UIDs to include in the report. Required for most report types.
</ParamField>

<ParamField body="columns" type="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
  * `isCheck` (boolean, optional): Whether this is a checkbox/boolean column

  If omitted, report uses default columns.
</ParamField>

## 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:** `places` (locations)

#### `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:** `places` (locations)

### 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>,
  "error": "Error message description"
}
```

### Example Usage

<RequestExample>
  ```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@company.com", "jane@company.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@company.com"],
      "format": "xlsx",
      "reporttype": "mileage",
      "columns": [
        {"key": "date"},
        {"key": "distance"},
        {"key": "from"},
        {"key": "to"}
      ]
    }
  }' > mileage-report.xlsx
  ```
</RequestExample>

### Notes

* Maximum date ranges vary by report type to ensure performance
* Some reports require specific parameters (e.g., places for place-based reports)
* 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