> ## 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. # Save a report > Saves a report request with formats, an optional schedule and recipients. A scheduled report needs at least one recipient; when its request has no period it gets the schedule's default (day: yesterday, week: lastWeek, month: lastMonth). Scheduled reports are sent by e-mail to the recipients (attached, as a link, or to the inbox). Answers 201. Admins, operators and the company key may call it; workers get 403 permission_denied. jobs, form-answers and visit-report need a Dispatch plan (403 on a Location plan). Same {data, error, meta} envelope; errors here use the codes invalid_request (400), permission_denied (403) and internal_error (500). ## OpenAPI ````yaml v1/openapi.json POST /reports/saved openapi: 3.1.0 info: title: Hellotracks REST API version: '1' description: >- Plain REST resources over HTTPS, for tools, automations and services. The ht command line is built on it. contact: email: api@hellotracks.com servers: - url: https://api.hellotracks.com/v1 security: - ApiKey: [] tags: - name: Sign-up and sign-in description: >- Create a company or get an API key by an emailed code, without a key; and check which account a key belongs to. - name: Company description: The company the API key belongs to, with its settings and teams. - name: Members description: 'The people in the company: admins, operators and workers.' - name: API keys description: 'The company''s API keys: list, create, revoke and delete.' - name: Jobs description: 'Jobs: work at a location on a date, assigned to a member.' - name: Places description: 'Places: customer sites and other saved locations with a check-in radius.' - name: Zones description: 'Zones: the company''s geofences.' - name: Routing description: Route optimization for one member's day. - name: ETA pages description: >- Live ETA pages (eta.page links) that show a job's recipient when the worker arrives. - name: Maps description: Rendered maps as GeoJSON, and public map share links. - name: Timesheets description: Clock-in and clock-out entries of members, with totals, and editing them. - name: Forms description: >- Form templates, submitted forms, attachments for file and image fields, and forms linked to places and jobs. - name: Alerts description: >- Alert rules (configs) that watch members, places and zones, and the alerts (instances) they raised. - name: Reports description: >- Reports: the newer reporting API (catalog, preview, run, saved) and the older one (types, generate, jobs, uploads, recurring). - name: Webhooks description: URLs Hellotracks calls when jobs, check-ins, clock-ins or alerts happen. paths: /reports/saved: post: tags: - Reports summary: Save a report description: >- Saves a report request with formats, an optional schedule and recipients. A scheduled report needs at least one recipient; when its request has no period it gets the schedule's default (day: yesterday, week: lastWeek, month: lastMonth). Scheduled reports are sent by e-mail to the recipients (attached, as a link, or to the inbox). Answers 201. Admins, operators and the company key may call it; workers get 403 permission_denied. jobs, form-answers and visit-report need a Dispatch plan (403 on a Location plan). Same {data, error, meta} envelope; errors here use the codes invalid_request (400), permission_denied (403) and internal_error (500). operationId: createSavedReport requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SavedReportInput' example: name: Weekly timesheet request: report: timesheet view: perPerson who: kind: people memberUids: - a1b2c3 formats: - xlsx schedule: frequency: week weekday: 1 hour: 7 minute: 0 recipients: memberUids: - a1b2c3 emails: - office@example.com delivery: attach responses: '201': description: Created content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' properties: data: type: object properties: saved: $ref: '#/components/schemas/SavedReport' example: data: saved: id: 6560000000000000000000b1 classic: false name: Weekly timesheet report: timesheet request: report: timesheet view: perPerson period: lastWeek compare: true who: kind: people teamIds: [] memberUids: - a1b2c3 places: kind: all field: '' value: '' teamIds: [] placeUids: [] options: {} format: xlsx formats: - xlsx schedule: frequency: week weekdays: [] weekday: 1 monthDay: 1 hour: 7 minute: 0 scheduleText: Every Monday at 7:00, covering last week recipients: memberUids: - a1b2c3 emails: - office@example.com delivery: attach status: active nextRunTs: 1762153200000 lastSentTs: 0 lastStatus: '' lastError: '' createdTs: 1761901100000 createdBy: a1b2c3 error: null meta: path: /v1/reports/saved method: POST '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: SavedReportInput: type: object description: >- A saved report. PATCH replaces the whole saved report: request is required there too, and fields left out go back to their defaults. required: - request properties: name: type: string maxLength: 120 description: Defaults to the report's title. request: $ref: '#/components/schemas/ReportRequest' formats: type: array maxItems: 3 items: type: string enum: - pdf - xlsx - csv - json description: Defaults to request.format or the report's default format. schedule: $ref: '#/components/schemas/ReportSchedule' recipients: $ref: '#/components/schemas/ReportRecipients' delivery: type: string enum: - attach - link - inbox default: attach status: type: string enum: - active - paused description: Default active on create; kept on update when left out. Envelope: type: object properties: data: description: The payload. error: type: 'null' meta: $ref: '#/components/schemas/Meta' SavedReport: type: object properties: id: type: string classic: type: boolean const: false name: type: string report: type: string enum: - team-week - jobs - place-visits - timesheet - mileage - alerts - form-answers - visit-report request: $ref: '#/components/schemas/ReportRequest' formats: type: array items: type: string schedule: $ref: '#/components/schemas/ReportSchedule' scheduleText: type: string description: The schedule as a sentence in the company's language. recipients: $ref: '#/components/schemas/ReportRecipients' delivery: type: string enum: - attach - link - inbox status: type: string enum: - active - paused nextRunTs: type: integer format: int64 description: Next send time in ms; 0 when paused or not scheduled. lastSentTs: type: integer format: int64 lastStatus: type: string lastError: type: string createdTs: type: integer format: int64 description: Milliseconds since the epoch. createdBy: type: string fromClassic: type: object description: Only when moved over from an older recurring report. properties: id: type: string type: type: string format: type: string trialUntilDay: type: integer description: >- YYYYMMDD; only when the older schedule keeps running alongside for a while. ReportRequest: type: object description: >- What a report is asked for. A period is either a relative period (resolved against the company's today when the report runs) or fixed days fromDay/untilDay. With neither, last week is used. The period may not be longer than the report's maxDays. required: - report properties: report: type: string enum: - team-week - jobs - place-visits - timesheet - mileage - alerts - form-answers - visit-report view: type: string description: One of the report's views; empty = the first view. period: type: string enum: - today - yesterday - thisWeek - lastWeek - thisMonth - lastMonth - last7Days - last30Days description: Weeks start on Monday; "last" periods never include today. fromDay: type: integer description: >- First day as a number YYYYMMDD (e.g. 20261001). Used when period is empty. example: 20261001 untilDay: type: integer description: Last day as a number YYYYMMDD, inclusive. example: 20261031 compare: type: boolean default: true description: Compare with the period before. who: type: object description: People in the report. Missing = everyone the caller may see. properties: kind: type: string enum: - everyone - teams - people default: everyone teamIds: type: array items: type: integer memberUids: type: array items: type: string places: type: object description: >- Places in the report (reports with the places scope). Missing = all active places. properties: kind: type: string enum: - all - field - teams - list default: all field: type: string description: Custom field name, for kind field. value: type: string description: Custom field value, for kind field. teamIds: type: array items: type: integer placeUids: type: array items: type: string jobId: type: string description: The job, for visit-report. options: type: object additionalProperties: type: string description: >- Report options; values are read as strings. Known keys: language (e.g. "de"), formId (form template id, form-answers), status (jobs filter, comma-separated), table (which table the CSV holds), columns (a list of {key, name}, as JSON text or an array). format: type: string enum: - pdf - xlsx - csv - json description: >- For preview: csv shows the CSV table; for run: used when formats is empty. ReportSchedule: type: object description: >- When a saved report sends itself, in the company's time zone. Missing = none (run by hand). properties: frequency: type: string enum: - none - day - week - month default: none weekdays: type: array items: type: integer minimum: 1 maximum: 7 description: 'For day: 1 = Monday ... 7 = Sunday; defaults to 1-5.' weekday: type: integer minimum: 1 maximum: 7 default: 1 description: For week. monthDay: type: integer minimum: 1 maximum: 28 default: 1 description: For month. hour: type: integer minimum: 0 maximum: 23 default: 7 minute: type: integer minimum: 0 maximum: 59 default: 0 ReportRecipients: type: object properties: memberUids: type: array items: type: string description: Members of the company (403 when not). emails: type: array items: type: string format: email description: Lower-cased and de-duplicated. At most 50 recipients in all. Meta: type: object properties: path: type: string description: The request path, without /v1. example: /jobs method: type: string example: GET ErrorEnvelope: type: object properties: data: type: 'null' error: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/Meta' Error: type: object required: - code - message properties: code: type: string description: Stable error code for programs. enum: - invalid_request - invalid_format - invalid_data - invalid_api_key - unknown_user - authentication_failed - forbidden - not_found - already_exists - throttled - not_ready - clock_invalid - force_logout - internal_error - unknown_error message: type: string description: Why it failed, for people. responses: BadRequest: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: invalid_request message: date must be YYYY-MM-DD meta: path: /jobs method: GET Unauthorized: description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: invalid_api_key message: Invalid Hellotracks API key. meta: path: /jobs method: GET Forbidden: description: The key may not do this. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: forbidden message: No permission. meta: path: /jobs method: GET TooManyRequests: description: Too many requests; slow down. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: throttled message: Too many requests. meta: path: /jobs method: GET ServerError: description: Hellotracks failed; retry later. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: internal_error message: Hellotracks API is temporarily unavailable. meta: path: /jobs method: GET securitySchemes: ApiKey: type: apiKey in: header name: API-Key description: >- Your API key, from More → API & Integrations in the dashboard, or from ht signup / ht auth login. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.