Riferimento dell'API pubblica

L'API pubblica di Workify360 Focus consente ai tuoi script e strumenti di leggere report e dati sul tempo e di apportare modifiche con le stesse regole della dashboard. L'API pubblica, le chiavi API e i webhook fanno parte del piano Premium.

Le operazioni di questa pagina restano retrocompatibili. Il documento OpenAPI delle stesse operazioni, in formato leggibile dalle macchine:

https://api.focus.workify360.com/v1/openapi/public.json

Generato dalla versione 0.1.0 del contratto dell'API (c95fb97bb49a).

Autenticazione

Invia una chiave API personale nell'header Authorization di ogni richiesta. Una chiave appartiene alla persona che l'ha creata, agisce come quella persona e non fa mai più di quanto consenta il suo ruolo attuale. Una richiesta con una chiave mancante, errata, scaduta o revocata riceve 401 con il codice unauthorized.

curl https://api.focus.workify360.com/v1/me \
  -H "Authorization: Bearer w360_pat_…"

Come creare chiavi, assegnare loro gli scope e revocarle: Chiavi API e API pubblica

Scope

Ogni operazione richiede uno scope, indicato accanto a ciascuna. Una chiave può usare un'operazione quando possiede quello scope e il ruolo, i team e il piano attuali del suo titolare consentono la richiesta, esattamente come nella dashboard.

Scope	Cosa consente
`me`	Il tuo profilo e il tuo timer
`reports:read`	Lettura di report, voci di tempo, assenze, turni, team, progetti, task ed esportazioni
`time:write`	Aggiunta e modifica di voci di tempo, assenze, turni, task e tempo assegnato ai task, e approvazione o rifiuto delle richieste
`org:admin`	Gestione di membri, team, inviti e progetti
`webhooks:manage`	Gestione degli endpoint webhook

Limiti di frequenza

Ogni chiave può inviare 600 unità al minuto e un'organizzazione 1.800 per tutte le sue chiavi insieme. Una richiesta che modifica qualcosa (qualsiasi metodo diverso da GET e HEAD) conta come due unità, qualsiasi altra richiesta come una. Una chiave può inoltre inviare al massimo 60 unità in una volta, ricaricate a 10 al secondo: più di 60 letture (o 30 modifiche) inviate a raffica ricevono 429 anche restando sotto le 600 al minuto.

Header	Significato
`RateLimit: "key";r=598;t=2`	In ogni risposta conteggiata: le unità rimaste alla chiave e i secondi che mancano al ripristino completo
`RateLimit-Policy: "key";q=600;w=60, "tenant";q=1800;w=60`	In ogni risposta conteggiata: i limiti al minuto della chiave e dell'organizzazione
`Retry-After: 12`	Con 429 (codice `rate_limited`): i secondi da attendere prima della richiesta successiva

Errori

Un errore è un problem document RFC 9457 (Content-Type: application/problem+json). code è un codice snake_case stabile, da usare nella logica del tuo programma; title è un testo in inglese per i log. type è l'indirizzo della guida del codice, https://workify360.com/help/errors/<code>/ con ogni _ scritto come -, che apre l'articolo della guida che spiega il codice, quando esiste.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://workify360.com/help/errors/forbidden/",
  "title": "Forbidden",
  "status": 403,
  "code": "forbidden",
  "action": "webhooks.manage",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Alcuni problemi contengono campi aggiuntivi: errors (gli errori sui campi di 422 validation_failed), action (il permesso a cui si riferisce un 403 forbidden), requiredPlan (402 feature_not_in_plan), retryAfterSeconds (429 e 503) e traceId (indicalo quando contatti l'assistenza).

Stato	Codice	Quando
400	`invalid_request`	Un parametro è malformato o mancante
401	`unauthorized`	La chiave è mancante, errata, scaduta o revocata, oppure il suo titolare ha lasciato l'organizzazione
402	`feature_not_in_plan`, `subscription_read_only`	Il piano non include la funzionalità, oppure l'abbonamento è in sola lettura
403	`forbidden`, `feature_not_enabled`	Alla chiave manca lo scope, oppure il ruolo, i team o le impostazioni attuali del suo titolare non consentono la richiesta
412	`version_conflict`	La versione in `If-Match` non è più quella attuale; rileggi la risorsa
422	`validation_failed`	Il body non è valido; `errors` elenca i campi
428	`precondition_required`	L'operazione richiede un header `If-Match` con la versione che hai letto
429	`rate_limited`	Troppe richieste; attendi i secondi indicati in `Retry-After`

I codici che hanno un articolo nella guida sono link nell'elenco delle operazioni.

Webhook

Invece di interrogare l'API più e più volte, un tuo endpoint può ricevere una richiesta HTTPS firmata quando qualcosa cambia. Gli eventi, il formato della richiesta, come verificare la firma in Node.js e Python, i tentativi ripetuti e la rotazione del segreto sono spiegati nell'articolo della guida: Webhook

Operazioni

Raggruppate per area. I riepiloghi e le descrizioni dei campi provengono dal contratto dell'API.

Assenze

GET `/v1/absences` Scope: `reports:read`

List absences overlapping a range.

Parametri

Nome	Posizione	Tipo	Descrizione
`from`	query	string (date)
`to`	query	string (date)	At most 366 days after `from`.
`userId`	query	string (uuid)
`teamId`	query	string (uuid)
`status`	query	string
`typeId`	query	string (uuid)
`cursor`	query	string
`limit`	query	integer (int32)

Risposte

200 AbsencePage

Errori

400 invalid_request, range_too_long
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)

POST `/v1/absences` Scope: `time:write`

Request (or record) an absence.

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`obbligatorio	header	string	Required: the same key and body return the first answer

Body della richiesta

AbsenceRequest

Risposte

201 AbsenceDto

Errori

400 invalid_absence_unit, invalid_absence_range, invalid_half, unit_not_allowed, range_too_far
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 absence_type_not_found
409 overlaps_absence, insufficient_balance, absence_type_inactive

POST `/v1/absences/{id}/decision` Scope: `time:write`

Approve or reject an absence (the G1 endpoint of the calendar).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Id
`If-Match`obbligatorio	header	string	ETag of the resource (`"v<n>"`); missing: 428, stale: 412

Body della richiesta

CalendarDecisionRequest

Risposte

200 AbsenceDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 absence_not_found
409 absence_not_pending, insufficient_balance
412 version_conflict
428 precondition_required (no If-Match)

Attività

GET `/v1/activity/day` Scope: `reports:read`

One user's local day (My Focus, the timeline): totals, productivity, attendance, day plan, slots, apps, time entries.

Parametri

Nome	Posizione	Tipo	Descrizione
`date`	query	string (date)	The user's local day (required).
`userId`	query	string (uuid)	Default: the caller; another user must be visible (else 403).

Risposte

200 ActivityDayDto

Errori

400 invalid_request (malformed or missing parameter)
402 feature_not_in_plan
403 forbidden (action = the permission; a user outside the scope)

Assegnazioni del tempo

GET `/v1/allocations` Scope: `reports:read`

A person's allocations of a range of local days (the caller's, the people they manage, and the time on the projects they manage).

Parametri

Nome	Posizione	Tipo	Descrizione
`userId`	query	string (uuid)	Default: the caller.
`from`	query	string (date)	Local date, included.
`to`	query	string (date)	Local date, included; at most 93 days after `from`.
`projectId`	query	string (uuid)
`cursor`	query	string
`limit`	query	integer (int32)	1–200 (default 200).

Risposte

200 AllocationPage

Errori

400 invalid_request (malformed parameter), range_too_long
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission; a person outside the scope)

POST `/v1/allocations` Scope: `time:write`

Put time on a project: entered (manual) or tracked time assigned afterwards (assignment); for another person with allocations.write.

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`	header	string \| null	The same key and body return the first answer (a different body: 422 idempotency_key_reused)

Body della richiesta

AllocationCreateRequest

Risposte

201 AllocationCreatedDto

Errori

400 range_in_future, range_too_old
402 feature_not_in_plan, subscription_read_only
403 forbidden, project_not_trackable
404 project_not_found, task_not_found, member_not_found
409 allocation_overlaps, allocation_billed, project_not_active
422 validation_failed, allocation_too_long, task_not_in_project

Esportazioni

POST `/v1/exports` Scope: `reports:read`

Request an export: the file is produced by a worker job with the requester's current role.

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`obbligatorio	header	string	Required: the same key and body return the first answer

Body della richiesta

CreateExportRequest

Risposte

202 ExportJobDto

Errori

400 invalid_dataset, range_too_long, too_many_columns_for_pdf
402 feature_not_in_plan
403 forbidden (action = the permission; a user or team outside the scope; includeCosts without the right to see amounts)
404 template_not_found
409 export_not_available
422 validation_failed
429 too_many_exports
503 export_storage_unavailable

GET `/v1/exports/{id}` Scope: `reports:read`

One export job (poll every 2 s).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Id

Risposte

200 ExportJobDto

Errori

402 feature_not_in_plan
403 forbidden (action = the permission; a user or team outside the scope)
404 export_not_found

Il mio profilo

GET `/v1/me` Scope: `me`

The signed-in person, their membership, organization, rights and session.

Risposte

200 MeDto

Errori

401 unauthorized

Membri

POST `/v1/invitations` Scope: `org:admin`

Invite a person.

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`obbligatorio	header	string	Required: 1–255 printable ASCII characters

Body della richiesta

CreateInvitation

Risposte

201 InvitationResult

Errori

409 already_member
422 validation_failed, idempotency_key_reused

GET `/v1/members` Scope: `org:admin`

List members.

Parametri

Nome	Posizione	Tipo	Descrizione
`status`	query	string	Comma-separated statuses (default active,invited,suspended)
`teamId`	query	string (uuid)	Primary team
`role`	query	string	owner, admin, team_admin, manager or employee
`q`	query	string	Part of the name or e-mail (Turkish case folding)
`cursor`	query	string	Opaque cursor of the next page
`limit`	query	integer (int32)	1–200, default 50

Risposte

200 MemberPage

Errori

403 No right

GET `/v1/members/{id}` Scope: `org:admin`

One member.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Membership id

Risposte

200 MemberDto

Errori

404 member_not_found

PATCH `/v1/members/{id}` Scope: `org:admin`

Change a member's role, team, viewer teams, zone or tracking.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Membership id
`If-Match`obbligatorio	header	string	ETag of the member ("v<n>")

Body della richiesta

PatchMember

Risposte

200 MemberDto

Errori

400 self_change_forbidden, owner_immutable, role_not_assignable, team_required, viewer_teams_not_allowed
412 version_conflict
428 precondition_required

POST `/v1/members/{id}/reactivate` Scope: `org:admin`

Reactivate a suspended member.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Membership id

Risposte: 200 MemberDto

POST `/v1/members/{id}/suspend` Scope: `org:admin`

Suspend a member: the membership is suspended and every session of it in this organization ends.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Membership id

Risposte

200 MemberDto

Errori

409 conflict (an invitation is revoked instead)

Progetti

GET `/v1/projects` Scope: `reports:read`

The projects the caller sees (Owners and Admins: all; others: open ones, their teams and, read only, the projects of the people they manage).

Parametri

Nome	Posizione	Tipo	Descrizione
`status`	query	string	`active`, `on_hold` or `completed`.
`clientId`	query	string (uuid)
`q`	query	string	Name or code search (case-insensitive).
`includeArchived`	query	boolean
`mine`	query	boolean	Only the projects the caller may track time on.
`cursor`	query	string
`limit`	query	integer (int32)	1–200 (default 50).

Risposte

200 ProjectPage

Errori

400 invalid_request (malformed parameter)
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)

POST `/v1/projects` Scope: `org:admin`

Add a project (Owners and Admins).

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`	header	string \| null	The same key and body return the first answer (a different body: 422 idempotency_key_reused)

Body della richiesta

ProjectRequest

Risposte

201 ProjectDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 client_not_found
409 project_name_taken, project_code_taken
422 validation_failed (errors[] = field codes)

GET `/v1/projects/{id}` Scope: `reports:read`

One project (invisible projects are 404).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Project id

Risposte

200 ProjectDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 project_not_found

PUT `/v1/projects/{id}` Scope: `org:admin`

Change a project (Owners and Admins; the whole body).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Project id
`If-Match`obbligatorio	header	string	The ETag the caller read (412 version_conflict when it changed)

Body della richiesta

ProjectRequest

Risposte

200 ProjectDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 project_not_found, client_not_found
409 project_name_taken, project_code_taken, project_currency_locked
412 version_conflict
422 validation_failed (errors[] = field codes)
428 precondition_required (If-Match)

Report

GET `/v1/reports/productivity` Scope: `reports:read`

Productivity by day, week, month or range for the company, a team or a user.

Parametri

Nome	Posizione	Tipo	Descrizione
`from`	query	string (date)
`to`	query	string (date)	`day` 93 days, `week`, `month` and `range` 366.
`groupBy`	query	string	`day`, `week`, `month` or `range`.
`teamId`	query	string (uuid)
`userId`	query	string (uuid)

Risposte

200 PeriodReportDto

Errori

400 invalid_request (malformed parameter), invalid_group_by, range_too_long
402 feature_not_in_plan
403 forbidden (action = the permission; a user or team outside the scope)

GET `/v1/reports/projects` Scope: `reports:read`

Allocated time, billable time and the rate-layered amounts (Owners and Admins) of projects in a range, grouped by one or two of project, task, user, client and day, with the projects' budget use.

Parametri

Nome	Posizione	Tipo	Descrizione
`from`	query	string (date)	Local date, included.
`to`	query	string (date)	Local date, included; at most 366 days after `from`.
`groupBy`	query	string	One or two of `project` (default), `task`, `user`, `client`, `day`, comma separated.
`projectIds`	query	string	Comma-separated project ids.
`clientId`	query	string (uuid)
`userIds`	query	string	Comma-separated user ids (visible people only).
`teamId`	query	string (uuid)
`billable`	query	string	`all` (default), `billable` or `nonBillable`.
`includeProductive`	query	boolean	Also compute the productive time within the allocations (costly; default false).

Risposte

200 ProjectReportDto

Errori

400 invalid_request (malformed parameter), invalid_group_by, range_too_long
402 feature_not_in_plan
403 forbidden (action = the permission; a user or team outside the scope)

GET `/v1/reports/summary` Scope: `reports:read`

The summary of the visible users over a range.

Parametri

Nome	Posizione	Tipo	Descrizione
`from`	query	string (date)
`to`	query	string (date)	At most 93 days after `from`.
`teamId`	query	string (uuid)	Only the team's current members; the team must be visible (else 403).

Risposte

200 SummaryDto

Errori

400 invalid_request (malformed parameter), range_too_long
402 feature_not_in_plan
403 forbidden (action = the permission; a team outside the scope)

GET `/v1/reports/targets` Scope: `reports:read`

The apps, domains or hosts of the visible users over a range (Apps & URLs).

Parametri

Nome	Posizione	Tipo	Descrizione
`from`	query	string (date)
`to`	query	string (date)
`type`	query	string	`app`, `domain` or `host`.
`teamId`	query	string (uuid)
`userId`	query	string (uuid)
`q`	query	string	Search in the key and the name (.NET `search`).
`level`	query	string	`productive`, `unproductive` or `neutral`.
`categoryKey`	query	string
`unclassified`	query	boolean	Only targets without a category.
`cursor`	query	string
`limit`	query	integer (int32)	1–200, default 50.

Risposte

200 TargetListDto

Errori

400 invalid_request (malformed parameter or cursor), invalid_level, range_too_long
402 feature_not_in_plan
403 forbidden (action = the permission; a user or team outside the scope)

GET `/v1/reports/users/{userId}/daily` Scope: `reports:read`

A user's days of a range (computed days and the workdays without activity).

Parametri

Nome	Posizione	Tipo	Descrizione
`userId`obbligatorio	path	string (uuid)	User
`from`	query	string (date)
`to`	query	string (date)	At most 93 days after `from`.

Risposte

200 UserDailyDto

Errori

400 invalid_request (malformed parameter), range_too_long
402 feature_not_in_plan
403 forbidden (action = the permission; a user outside the scope)

Turni

GET `/v1/shifts` Scope: `reports:read`

List the shifts starting in a range.

Parametri

Nome	Posizione	Tipo	Descrizione
`from`	query	string (date)
`to`	query	string (date)
`teamId`	query	string (uuid)
`userId`	query	string (uuid)
`includeOpen`	query	boolean	Also open shifts (default true).

Risposte

200 ShiftListDto

Errori

400 invalid_request (malformed parameter)
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)

POST `/v1/shifts` Scope: `time:write`

Create a shift (assigned or open).

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`obbligatorio	header	string	Required: the same key and body return the first answer

Body della richiesta

ShiftBody

Risposte

201 ShiftDto

Errori

400 invalid_shift_time, invalid_break, open_shift_requires_team, …
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
409 overlaps_shift, shift_in_past

Task

GET `/v1/projects/{id}/tasks` Scope: `reports:read`

A visible project's tasks, by sort order.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Project id
`status`	query	string	`open`, `in_progress` or `done`.
`assigneeUserId`	query	string (uuid)
`includeArchived`	query	boolean
`cursor`	query	string
`limit`	query	integer (int32)	1–500 (default 200).

Risposte

200 TaskPage

Errori

400 invalid_request (malformed parameter)
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 project_not_found

POST `/v1/projects/{id}/tasks` Scope: `time:write`

Add a task (an Admin or the project's manager).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Project id
`Idempotency-Key`	header	string \| null	The same key and body return the first answer (a different body: 422 idempotency_key_reused)

Body della richiesta

TaskRequest

Risposte

201 TaskDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden, project_not_trackable (the assignee)
404 project_not_found
409 task_name_taken
422 validation_failed (errors[] = field codes)

GET `/v1/tasks/{id}` Scope: `reports:read`

One task of a visible project.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Task id

Risposte

200 TaskDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 task_not_found

PUT `/v1/tasks/{id}` Scope: `time:write`

Change a task (the whole body).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Task id
`If-Match`obbligatorio	header	string	The ETag the caller read (412 version_conflict when it changed)

Body della richiesta

TaskRequest

Risposte

200 TaskDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden, project_not_trackable (the assignee)
404 task_not_found
409 task_name_taken
412 version_conflict
422 validation_failed (errors[] = field codes)
428 precondition_required (If-Match)

Team

GET `/v1/teams` Scope: `reports:read`

List teams.

Parametri

Nome	Posizione	Tipo	Descrizione
`includeArchived`	query	boolean	Also archived teams (default false)
`cursor`	query	string	Opaque cursor of the next page
`limit`	query	integer (int32)	1–200, default 50

Risposte: 200 TeamPage

POST `/v1/teams` Scope: `org:admin`

Create a team (the G1 endpoint).

Body della richiesta

CreateTeam

Risposte

201 TeamDto

Errori

403 forbidden (action teams.create)
409 team_name_taken

PATCH `/v1/teams/{id}` Scope: `org:admin`

Rename a team or change its description.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Team id
`If-Match`obbligatorio	header	string	ETag of the team

Body della richiesta

PatchTeam

Risposte

200 TeamDto

Errori

409 team_name_taken

Voci di tempo

GET `/v1/time-entries` Scope: `reports:read`

List a user's time entries of a range (by start).

Parametri

Nome	Posizione	Tipo	Descrizione
`userId`	query	string (uuid)	Default: the caller.
`from`	query	string (date)	The entry's local day, required.
`to`	query	string (date)	At most 93 days after `from`.
`kind`	query	string	`offline` or `deletion`.
`status`	query	string	`pending`, `approved` or `rejected`.
`cursor`	query	string
`limit`	query	integer (int32)	1–500.

Risposte

200 TimeEntryPage

Errori

400 invalid_request, range_too_long, invalid_kind
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)

POST `/v1/time-entries` Scope: `time:write`

Add offline time or a deletion (for oneself, or for a user one manages: TimeEntryPolicy in the handler).

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`obbligatorio	header	string	Required: the same key and body return the first answer

Body della richiesta

CreateTimeEntryRequest

Risposte

201 TimeEntryDto

Errori

400 invalid_time_range, range_not_in_one_day, range_in_future, range_too_old, invalid_description, invalid_level, invalid_kind, project_not_supported
402 feature_not_in_plan, subscription_read_only
403 forbidden, offline_time_disabled, time_editing_disabled
404 user_not_found
409 overlaps_entry

GET `/v1/time-entries/{id}` Scope: `reports:read`

One time entry (invisible, missing and other tenants' entries are all 404).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Entry id

Risposte

200 TimeEntryDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 entry_not_found

PUT `/v1/time-entries/{id}` Scope: `time:write`

Replace an entry's editable fields.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Entry id
`If-Match`obbligatorio	header	string	ETag of the resource (`"v<n>"`); missing: 428, stale: 412

Body della richiesta

UpdateTimeEntryRequest

Risposte

200 TimeEntryDto

Errori

400 invalid_time_range, range_not_in_one_day, range_in_future, range_too_old, invalid_description, invalid_level, invalid_kind, project_not_supported
402 feature_not_in_plan, subscription_read_only
403 forbidden, offline_time_disabled, time_editing_disabled
404 entry_not_found
409 overlaps_entry
412 version_conflict
428 precondition_required (no If-Match)

DELETE `/v1/time-entries/{id}` Scope: `time:write`

Delete an entry (deleting a deletion restores the tracked time).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Entry id
`If-Match`obbligatorio	header	string	ETag of the resource (`"v<n>"`); missing: 428, stale: 412

Risposte

204 (nessun body)

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden, offline_time_disabled, time_editing_disabled
404 entry_not_found
412 version_conflict
428 precondition_required (no If-Match)

POST `/v1/time-entries/{id}/decision` Scope: `time:write`

Approve or reject a pending offline entry (the G1 endpoint of the time module).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	Entry id
`If-Match`obbligatorio	header	string	ETag of the resource (`"v<n>"`); missing: 428, stale: 412

Body della richiesta

TimeEntryDecisionRequest

Risposte

200 TimeEntryDto

Errori

400 invalid_request
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
404 entry_not_found
409 entry_not_pending
412 version_conflict
428 precondition_required (no If-Match)

Timer

GET `/v1/me/timer` Scope: `me`

The caller's timer (a segment due after 24 hours is stopped first).

Parametri

Nome	Posizione	Tipo	Descrizione
`If-None-Match`	header	string \| null	The ETag the caller holds (304 when unchanged)

Risposte

200 TimerDto · 304 (nessun body)

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)

POST `/v1/me/timer/start` Scope: `me`

Start the timer, or switch the running one to another project or task, at at (the client's clock).

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`	header	string \| null	The client's command id; a retry returns the first answer

Body della richiesta

TimerStartRequest

Risposte

200 TimerCommandResultDto

Errori

POST `/v1/me/timer/stop` Scope: `me`

Stop the running timer at at; its segment becomes allocations.

Parametri

Nome	Posizione	Tipo	Descrizione
`Idempotency-Key`	header	string \| null	The client's command id; a retry returns the first answer

Body della richiesta

TimerAtRequest

Risposte

200 TimerCommandResultDto

Errori

400 range_in_future
402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission)
409 allocation_overlaps
422 timer_command_too_old

Webhook

GET `/v1/webhook-endpoints` Scope: `webhooks:manage`

The tenant's webhook endpoints.

Parametri

Nome	Posizione	Tipo	Descrizione
`cursor`	query	string
`limit`	query	integer (int32)	1–200, default 50.

Risposte

200 WebhookEndpointPage

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = webhooks.manage), feature_not_enabled

POST `/v1/webhook-endpoints` Scope: `webhooks:manage`

Add a webhook endpoint (its signing secret is in this answer only; no Idempotency-Key: the answer holds a secret).

Body della richiesta

CreateWebhookEndpointRequest

Risposte

201 CreatedWebhookEndpointDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = webhooks.manage), feature_not_enabled
409 webhook_limit_reached
422 validation_failed, webhook_url_invalid, webhook_url_not_allowed, webhook_event_unknown

GET `/v1/webhook-endpoints/{id}` Scope: `webhooks:manage`

One webhook endpoint.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	The endpoint

Risposte

200 WebhookEndpointDto

Errori

403 forbidden (action = webhooks.manage), feature_not_enabled
404 webhook_endpoint_not_found

PATCH `/v1/webhook-endpoints/{id}` Scope: `webhooks:manage`

Change an endpoint: URL, description, events, pause or resume (active also opens a disabled endpoint), take it over.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	The endpoint
`If-Match`obbligatorio	header	string	The endpoint's ETag (`"v<n>"`)

Body della richiesta

UpdateWebhookEndpointRequest

Risposte

200 WebhookEndpointDto

Errori

403 forbidden (action = webhooks.manage), feature_not_enabled
404 webhook_endpoint_not_found
412 version_conflict
422 validation_failed, webhook_url_invalid, webhook_url_not_allowed, webhook_event_unknown
428 precondition_required

DELETE `/v1/webhook-endpoints/{id}` Scope: `webhooks:manage`

Delete an endpoint and its deliveries.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	The endpoint

Risposte

204 (nessun body)

Errori

403 forbidden (action = webhooks.manage), feature_not_enabled
404 webhook_endpoint_not_found

GET `/v1/webhook-endpoints/{id}/deliveries` Scope: `webhooks:manage`

The deliveries of an endpoint, newest first.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	The endpoint
`status`	query	string	`pending`, `succeeded`, `failed`, `dead`.
`eventType`	query	string
`cursor`	query	string	Opaque cursor of the next page.
`limit`	query	integer (int32)	1–200, default 50.

Risposte

200 WebhookDeliveryPage

Errori

403 forbidden (action = webhooks.manage), feature_not_enabled
404 webhook_endpoint_not_found

GET `/v1/webhook-endpoints/{id}/deliveries/{deliveryId}` Scope: `webhooks:manage`

One delivery with the body that was sent.

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	The endpoint
`deliveryId`obbligatorio	path	string	The delivery (a 64-bit integer)

Risposte

200 WebhookDeliveryDetailDto

Errori

403 forbidden (action = webhooks.manage), feature_not_enabled
404 webhook_endpoint_not_found, webhook_delivery_not_found

POST `/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry` Scope: `webhooks:manage`

Queue a failed or dead delivery again (attempts start over).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	The endpoint
`deliveryId`obbligatorio	path	string	The delivery (a 64-bit integer)

Risposte

202 AcceptedDto

Errori

403 forbidden (action = webhooks.manage), feature_not_enabled
404 webhook_endpoint_not_found, webhook_delivery_not_found

POST `/v1/webhook-endpoints/{id}/rotate-secret` Scope: `webhooks:manage`

A new signing secret (the previous one still signs for 24 hours).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	The endpoint

Risposte

200 RotatedWebhookSecretDto

Errori

403 forbidden (action = webhooks.manage), feature_not_enabled
404 webhook_endpoint_not_found

POST `/v1/webhook-endpoints/{id}/test` Scope: `webhooks:manage`

Send the webhook.test event (also to a paused endpoint).

Parametri

Nome	Posizione	Tipo	Descrizione
`id`obbligatorio	path	string (uuid)	The endpoint

Risposte

202 WebhookTestDto

Errori

403 forbidden (action = webhooks.manage), feature_not_enabled
404 webhook_endpoint_not_found
409 connection_paused (a disabled endpoint)

GET `/v1/webhook-events` Scope: `webhooks:manage`

The webhook event catalog and whether the tenant's plan has each event.

Risposte

200 WebhookEventsDto

Errori

402 feature_not_in_plan, subscription_read_only
403 forbidden (action = the permission), feature_not_enabled

Schemi

I body di richiesta e risposta usati dalle operazioni. I campi obbligatori sono contrassegnati.

AbsenceDto

An absence.

Campo	Tipo	Descrizione
`createdAt`obbligatorio	string (date-time)
`createdBy`obbligatorio	CalendarUserRefDto
`days`obbligatorio	number (double)	Σ `deductionByYear`; for types that do not deduct, the planned workdays (information only).
`decidedAt`	string (date-time) \| null
`decidedBy`	CalendarUserRefDto \| null
`decisionNote`	string \| null
`deductionByYear`obbligatorio	object	The balance deduction per year, e.g. `{"2026": 3.5}`; empty for types that do not deduct.
`end`obbligatorio	string (date-time)
`endDate`obbligatorio	string (date)
`endTime`	string \| null
`half`	string \| null
`id`obbligatorio	string (uuid)
`note`	string \| null
`permissions`obbligatorio	AbsencePermissionsDto
`start`obbligatorio	string (date-time)	UTC coverage start.
`startDate`obbligatorio	string (date)
`startTime`	string \| null
`status`obbligatorio	string
`timeZone`obbligatorio	string
`type`obbligatorio	AbsenceTypeRefDto
`unit`obbligatorio	string
`updatedAt`obbligatorio	string (date-time)
`user`obbligatorio	CalendarPersonDto
`userId`obbligatorio	string (uuid)

AbsencePage

GET /v1/absences.

Campo	Tipo	Descrizione
`items`obbligatorio	AbsenceDto[]
`nextCursor`	string \| null

AbsencePermissionsDto

Campo	Tipo	Descrizione
`canApprove`obbligatorio	boolean
`canCancel`obbligatorio	boolean
`canEdit`obbligatorio	boolean

AbsenceRequest

POST /v1/absences, PUT /v1/absences/{id} (the user never changes).

Campo	Tipo	Descrizione
`endDate`	string (date) \| null
`endTime`	string \| null
`half`	string \| null	`am` or `pm` for a half day.
`note`	string \| null
`startDate`	string (date) \| null
`startTime`	string \| null	Local `HH:mm` for `hours`.
`typeId`	string (uuid) \| null
`unit`	string \| null	`days`, `half_day` or `hours`.
`userId`	string (uuid) \| null	`null` = the caller.

AbsenceTypeRefDto

The absence's type as the absence shows it; name translated for a built-in type that was not renamed.

Campo	Tipo	Descrizione
`color`obbligatorio	string
`countsAsWorked`obbligatorio	boolean
`deductsFromBalance`obbligatorio	boolean
`id`obbligatorio	string (uuid)
`key`	string \| null
`name`obbligatorio	string
`paid`obbligatorio	boolean
`timeEffect`obbligatorio	string

AcceptedDto

202 Accepted of a queued job.

Campo	Tipo	Descrizione
`accepted`obbligatorio	boolean	Always `true`.

AccessDto

What the person may see and manage (FAZ1 AccessDto; focus_contracts::access::policy).

Campo	Tipo	Descrizione
`assignableRoles`obbligatorio	string[]
`canManageCompanySettings`obbligatorio	boolean
`canManageTeams`obbligatorio	boolean
`canManageUsers`obbligatorio	boolean
`manageTeamIds`obbligatorio	string[]
`scope`obbligatorio	string	`company`, `teams` or `self`.
`unassignedFallback`obbligatorio	boolean
`viewTeamIds`obbligatorio	string[]

ActivityDayDto

One user's local day. A day without activity is a 200 with zero totals, null arrival/leave and empty lists.

Campo	Tipo	Descrizione
`absenceCreditMs`obbligatorio	integer (int64)	A `worked` absence tops the worked time up to the expected work.
`activeMs`obbligatorio	integer (int64)	Window time ∩ not AFK (computer time only).
`afkCoverage`obbligatorio	boolean	False when no device reported AFK data (idle unknown).
`apps`obbligatorio	AppUsageDto[]	Daily totals, largest first.
`arrivalAt`	string (date-time) \| null
`atWorkMs`obbligatorio	integer (int64)
`attendance`	DayAttendanceDto \| null
`categories`obbligatorio	CategoryUsageDto[]	Active time per category (`null` key = uncategorized); offline time is in no category.
`classified`obbligatorio	boolean	False for a day written before the Phase 2 classification (all neutral).
`date`obbligatorio	string (date)
`dayEnd`obbligatorio	string (date-time)
`dayStart`obbligatorio	string (date-time)	The day's window: local midnight, or the end of the previous day's night shift window.
`deletedMs`obbligatorio	integer (int64)	Tracked time removed by approved deletions (part of idle).
`domains`obbligatorio	DomainUsageDto[]
`hosts`obbligatorio	HostUsageDto[]	Hosts with a URL, at most 50, largest first.
`idleMs`obbligatorio	integer (int64)
`leftAt`	string (date-time) \| null
`meetingMs`obbligatorio	integer (int64)	Active time the meeting apps exception turned from idle into active.
`offlineMs`obbligatorio	integer (int64)	Approved offline time outside the tracked active time.
`pendingOfflineMs`obbligatorio	integer (int64)	Pending offline entries of the day (information only).
`plan`	DayPlanDto \| null
`privateIntervals`obbligatorio	TimeIntervalDto[]	Private intervals of the day, merged and clipped, without detail.
`privateMs`obbligatorio	integer (int64)	Private time outside active and offline time.
`productivity`obbligatorio	DayProductivityDto
`recomputing`obbligatorio	boolean	The day waits in the recompute queue (the UI refetches every 15 s).
`slots`obbligatorio	ActivitySlotDto[]	One entry per 5-minute UTC slot with activity, by time.
`teamId`	string (uuid) \| null	The user's current primary team (its rules classify the day).
`timeEntries`obbligatorio	TimeEntryDto[]	Offline and deletion entries of every status overlapping the day's window, by start; the caller's permissions.
`timeZone`obbligatorio	string	The zone the day was computed in; the UI draws slots at their wall-clock time in it.
`userId`obbligatorio	string (uuid)
`workedMs`obbligatorio	integer (int64)	`activeMs + offlineMs`: the denominator of `productivity.productivityPct`.

ActivitySlotDto

Time in one 5-minute slot; activeMs includes approved offline time (offlineMs).

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`apps`obbligatorio	AppUsageDto[]
`neutralMs`obbligatorio	integer (int64)
`offlineMs`obbligatorio	integer (int64)
`productiveMs`obbligatorio	integer (int64)
`slotStart`obbligatorio	string (date-time)
`unproductiveMs`obbligatorio	integer (int64)

AffectedAllocationDto

An allocation replace changed.

Campo	Tipo	Descrizione
`change`obbligatorio	string	`trimmed`, `split` or `deleted`.
`id`obbligatorio	string (uuid)

AllocationCreateRequest

POST /v1/allocations (Idempotency-Key).

Campo	Tipo	Descrizione
`endedAt`	string (date-time) \| null	At most 24 hours after `startedAt`, at most 5 minutes in the future.
`isBillable`	boolean \| null
`note`	string \| null
`projectId`	string (uuid) \| null
`replace`	boolean \| null	Trim, split or delete the person's (unbilled) allocations it overlaps; otherwise an overlap is 409 `allocation_overlaps`.
`source`	string \| null	`manual` or `assignment` (`timer` only through the timer).
`startedAt`	string (date-time) \| null
`taskId`	string (uuid) \| null
`userId`	string (uuid) \| null	`null` = the caller; another person needs `allocations.write` and to be managed by the caller.

AllocationCreatedDto

POST /v1/allocations → 201.

Campo	Tipo	Descrizione
`affected`obbligatorio	AffectedAllocationDto[]
`allocation`obbligatorio	AllocationDto

AllocationDto

Time on a project.

Campo	Tipo	Descrizione
`createdAt`obbligatorio	string (date-time)
`createdBy`obbligatorio	NamedRefDto
`durationMs`obbligatorio	integer (int64)
`effectiveBillable`obbligatorio	boolean
`endedAt`obbligatorio	string (date-time)
`id`obbligatorio	string (uuid)
`invoiceId`	string (uuid) \| null	Set once the time is on an invoice.
`isBillable`	boolean \| null	`null` takes the task's, then the project's value.
`localDate`obbligatorio	string (date)	The start's day in the person's zone (rates, reports).
`note`	string \| null
`permissions`obbligatorio	AllocationPermissionsDto
`project`obbligatorio	ProjectRefDto
`source`obbligatorio	string	`timer`, `manual` or `assignment`.
`startedAt`obbligatorio	string (date-time)
`task`	NamedRefDto \| null
`timeZone`obbligatorio	string
`updatedAt`obbligatorio	string (date-time)
`userId`obbligatorio	string (uuid)
`version`obbligatorio	integer (int64)	The row version: `If-Match: "v<version>"` of a change (the same value as the resource's `ETag`).

AllocationPage

GET /v1/allocations.

Campo	Tipo	Descrizione
`items`obbligatorio	AllocationDto[]
`nextCursor`	string \| null

AllocationPermissionsDto

What the caller may do with an allocation (a billed one is locked).

Campo	Tipo	Descrizione
`delete`obbligatorio	boolean
`edit`obbligatorio	boolean

AppTotalDto

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`appKey`obbligatorio	string
`categoryKey`	string \| null
`level`	string \| null	Level in the response's `levelContext`.
`name`obbligatorio	string
`percentage`obbligatorio	number (double)	Share of the range's worked time (0–100, one decimal).

AppUsageDto

An app's time; offline rows use the reserved keys _offline_<level> with name: "Offline time" and levelSource: "offline".

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`appKey`obbligatorio	string
`categoryKey`	string \| null
`level`	string \| null	The app's own rule (`productive`, `unproductive`, `neutral`).
`levelSource`	string \| null	`team`, `company`, `default` or `offline`.
`name`obbligatorio	string

BudgetDto

A project's budget: hours (minutes) or an amount in the project's currency (amountMinor).

Campo	Tipo	Descrizione
`amountMinor`	integer (int64) \| null
`kind`	string \| null	`hours` or `amount`.
`minutes`	integer (int64) \| null

BudgetRequest

The budget of a project request (kind hours with minutes, or amount with amountMinor).

Campo	Tipo	Descrizione
`amountMinor`	integer (int64) \| null
`kind`	string \| null
`minutes`	integer (int64) \| null

CalendarDecisionRequest

{decision, note?} of the decision endpoints (approve or reject; the note at most 500 characters).

Campo	Tipo	Descrizione
`decision`	string \| null
`note`	string \| null

CalendarPersonDto

A user with the current team.

Campo	Tipo	Descrizione
`fullName`	string \| null
`id`obbligatorio	string (uuid)
`teamId`	string (uuid) \| null
`teamName`	string \| null

CalendarUserRefDto

A user reference (names from the directory; null when unknown).

Campo	Tipo	Descrizione
`fullName`	string \| null
`id`obbligatorio	string (uuid)

CapabilitiesDto

Subscription capabilities.

Campo	Tipo	Descrizione
`features`obbligatorio	string[]
`readOnly`obbligatorio	boolean

CategoryUsageDto

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`categoryKey`	string \| null	`null` = uncategorized.

CreateExportRequest

POST /v1/exports: definition is the full definition the dialog shows; without it the saved template (templateId) or the built-in one (templateKey) gives it.

Campo	Tipo	Descrizione
`definition`	ExportDefinitionDto \| null
`from`	string (date) \| null
`locale`	string \| null	`tr` or `en`.
`templateId`	string (uuid) \| null
`templateKey`	string \| null
`to`	string (date) \| null

CreateInvitation

POST /v1/invitations.

Campo	Tipo	Descrizione
`email`obbligatorio	string
`fullName`obbligatorio	string
`locale`	string \| null	Language of the e-mail and the acceptance page (`tr`, `en`); the organization's default otherwise.
`role`obbligatorio	string	`admin`, `team_admin`, `manager` or `employee`.
`teamId`	string (uuid) \| null
`timeZone`	string \| null
`viewerTeamIds`	string (uuid)[]

CreateTeam

POST /v1/teams.

Campo	Tipo	Descrizione
`description`	string \| null	At most 500 characters.
`name`obbligatorio	string	1–100 characters, unique among active teams (Turkish case folding).

CreateTimeEntryRequest

POST /v1/time-entries (the .NET CreateTimeEntryRequest).

Campo	Tipo	Descrizione
`description`	string \| null	Offline: 1–500 characters; deletion: optional reason (at most 500).
`end`	string (date-time) \| null
`kind`	string \| null	`offline` or `deletion`.
`level`	string \| null	Offline only (default `productive`).
`projectId`	string (uuid) \| null	Must be `null` (400 `project_not_supported`).
`start`	string (date-time) \| null
`userId`	string (uuid) \| null	`null` = the caller; a manager may add time for a user it manages.

CreateWebhookEndpointRequest

POST /v1/webhook-endpoints.

Campo	Tipo	Descrizione
`description`	string \| null	≤ 200 characters.
`eventTypes`obbligatorio	string[]	1–50 catalog event types of the tenant's plan.
`url`obbligatorio	string	`https://…` (≤ 2048; no user info, no fragment; every resolved address public).

CreatedWebhookEndpointDto

CreatedWebhookEndpointDto: the endpoint and its signing secret, shown once.

Campo	Tipo	Descrizione
`endpoint`obbligatorio	WebhookEndpointDto
`secret`obbligatorio	string	`whsec_<base64>`: shown once, never again.

DailyHolidayDto

A holiday of a daily report day.

Campo	Tipo	Descrizione
`half`	string \| null
`key`obbligatorio	string
`name`obbligatorio	string	English name; `nameTr` is the Turkish one.
`nameTr`obbligatorio	string

DayAbsenceDto

The dominant absence of a day (/v1/reports/users/{userId}/daily days[].absence).

Campo	Tipo	Descrizione
`color`obbligatorio	string
`fraction`obbligatorio	number (double)	The day's approved absence coverage (0–1).
`half`	string \| null
`typeKey`	string \| null
`typeName`	string \| null
`unit`obbligatorio	string

DayAttendanceDto

Attendance of the day on the day plan.

Campo	Tipo	Descrizione
`expectedEnd`	string (date-time) \| null
`expectedStart`	string (date-time) \| null
`flexible`obbligatorio	boolean
`lateByMs`obbligatorio	integer (int64)
`lateToleranceMinutes`obbligatorio	integer (int32)
`leftEarly`obbligatorio	boolean
`leftEarlyByMs`obbligatorio	integer (int64)
`status`obbligatorio	string	`onTime`, `late`, `absent`, `notStarted`, `dayOff`, `onLeave`, `holiday`.
`targetMs`obbligatorio	integer (int64)	The plan's target (the Effectiveness % denominator).
`workday`obbligatorio	boolean

DayPlanDto

The day plan of one user's day.

Campo	Tipo	Descrizione
`absences`obbligatorio	PlanAbsenceDto[]	Approved and pending absences covering the day (only approved ones change the numbers).
`expectedEnd`	string (date-time) \| null
`expectedStart`	string (date-time) \| null
`expectedWorkMs`obbligatorio	integer (int64)	Overtime target (`base × (1 − fLeave)`).
`holiday`	HolidayRefDto \| null
`kind`obbligatorio	string	`schedule`, `shift`, `dayOff` or `holiday`.
`leaveFraction`obbligatorio	number (double)	The approved absence coverage `f` (0–1).
`shifts`obbligatorio	PlanShiftDto[]	Shifts starting on the day, by start.
`targetMs`obbligatorio	integer (int64)	Effectiveness % denominator (`base × (1 − f)`).
`workday`obbligatorio	boolean

DayProductivityDto

A day's time by productivity level (productive + unproductive + neutral = workedMs).

Campo	Tipo	Descrizione
`effectivenessPct`	number (double) \| null	productive ÷ target × 100 (not capped); `null` without a target.
`neutralMs`obbligatorio	integer (int64)
`productiveMs`obbligatorio	integer (int64)
`productivityPct`	number (double) \| null	productive ÷ worked × 100, one decimal; `null` without worked time.
`targetMs`obbligatorio	integer (int64)
`unproductiveMs`obbligatorio	integer (int64)

DayTotalDto

One local day of a summary.

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`activeUserCount`obbligatorio	integer (int32)
`atWorkMs`obbligatorio	integer (int64)
`date`obbligatorio	string (date)
`idleMs`obbligatorio	integer (int64)
`neutralMs`obbligatorio	integer (int64)
`offlineMs`obbligatorio	integer (int64)
`privateMs`obbligatorio	integer (int64)
`productiveMs`obbligatorio	integer (int64)
`productivityPct`	number (double) \| null
`unproductiveMs`obbligatorio	integer (int64)

DomainTotalDto

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`categoryKey`	string \| null
`domain`obbligatorio	string
`level`	string \| null
`percentage`obbligatorio	number (double)

DomainUsageDto

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`categoryKey`	string \| null
`domain`obbligatorio	string
`level`	string \| null
`levelSource`	string \| null

EmailVerificationDto

Where the person stands with the e-mail verification (owner decision 3 Oct 2026, focus_auth::email_gate).

Campo	Tipo	Descrizione
`dueAt`	string (date-time) \| null	The deadline of an unverified account (`Identity__EmailVerificationGraceHours` after its creation).
`state`obbligatorio	string	`verified`, `not_required` (an account that never has to verify: invited, imported, SCIM, IdP-verified), `pending` (unverified, before `dueAt`) or `overdue` (after `dueAt`: every request but a few answers 403 `email_verification_required`).

ExportDefinitionDto

What an export contains (FAZ4 §6.1; focus_contracts::reports::export::ExportDefinition on the wire); a saved template stores it without the date range. Every field is optional so that the validator reports what is wrong (422 validation_failed with errors[{field, code}]).

Campo	Tipo	Descrizione
`columns`	string[] \| null	Column keys of the dataset in file order (1–40; a PDF at most 12).
`csvDialect`	string \| null	`standard` (default) or `excel-tr` (csv only).
`dataset`	string \| null
`durationFormat`	string \| null	`hms` (default), `hours` or `minutes`.
`filters`	ExportFiltersDto \| null
`format`	string \| null	`xlsx`, `csv` or `pdf`.
`groupBy`	string \| null	`day`, `week`, `month`, `range` or `none` (the dataset decides).
`options`	ExportOptionsDto \| null

ExportFiltersDto

Who is exported: a team, some users, or (neither) everyone the requester can see.

Campo	Tipo	Descrizione
`includeInactiveUsers`	boolean
`teamId`	string \| null
`userIds`	string \| null[] \| null

ExportJobDto

An export job as the panel lists and polls it.

Campo	Tipo	Descrizione
`createdAt`obbligatorio	string (date-time)
`dataset`obbligatorio	string
`errorCode`	string \| null	`too_many_rows`, `too_many_rows_for_pdf`, `access_lost`, `feature_not_in_plan`, `canceled`, `internal_error`.
`expiresAt`	string (date-time) \| null
`fileName`	string \| null
`fileSize`	integer (int64) \| null
`finishedAt`	string (date-time) \| null
`format`obbligatorio	string
`from`obbligatorio	string (date)
`groupBy`	string \| null
`id`obbligatorio	string (uuid)
`locale`obbligatorio	string
`progress`obbligatorio	integer (int32)	0–100.
`rowCount`	integer (int32) \| null
`startedAt`	string (date-time) \| null
`status`obbligatorio	string	`queued`, `running`, `succeeded`, `failed`, `canceled`, `expired`.
`templateId`	string (uuid) \| null
`templateKey`	string \| null
`templateName`	string \| null	The saved template's name, while it still exists.
`to`obbligatorio	string (date)

ExportOptionsDto

Dataset options; each applies to one dataset and is ignored by the others.

Campo	Tipo	Descrizione
`include`	string \| null	`titles`: `titles`, `urls` or `both` (default).
`includeCosts`	boolean \| null	`projects` (Faz 6): fill the rate, amount and currency columns (needs `projects.costs.read`, else 403).
`includeOpen`	boolean \| null	`shifts`: also open shifts.
`splitByUser`	boolean \| null	`applications`: one row per user and target.
`statuses`	string \| null[] \| null	`offline_time` / `absence`: status filter (default `approved`).
`targetType`	string \| null	`applications`: `app` (default), `domain` or `host`.

FieldError

One field error of a 400/422 body.

Campo	Tipo	Descrizione
`code`obbligatorio	string	Stable snake_case code (`required`, `too_long`, `invalid`, ...).
`field`obbligatorio	string	JSON path of the field in camelCase (`name`, `items[2].start`), or the parameter/header name.
`message`	string \| null

HolidayRefDto

A holiday of a day (both names; name is the English one).

Campo	Tipo	Descrizione
`half`	string \| null
`key`obbligatorio	string	Built-in key (`republic_day`, …) or `custom`.
`name`obbligatorio	string
`nameEn`obbligatorio	string
`nameTr`obbligatorio	string
`source`	string \| null	`builtin` or `tenant`.

HostUsageDto

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`domain`	string \| null
`host`obbligatorio	string
`level`obbligatorio	string
`levelSource`obbligatorio	string
`matchedKey`	string \| null	Key of the matching domain rule; `null` for the default.

InvitationEmail

What happened to the invitation e-mail.

Campo	Tipo	Descrizione
`acceptUrl`	string \| null	The acceptance link, only when no e-mail is sent (`not_configured`, `suppressed_reserved`) and only in the fresh answer (share it by hand).
`status`obbligatorio	string	`queued`; `not_configured` when no e-mail provider is set up; `suppressed_reserved` when the address is an RFC 2606 / RFC 6761 reserved name (`example.com`, `*.test`, …) that is never e-mailed. Clients treat `suppressed_reserved` like `not_configured`: nothing arrives, share `acceptUrl` by hand.

InvitationRef

{"id","expiresAt"} of a created or re-sent invitation.

Campo	Tipo	Descrizione
`expiresAt`obbligatorio	string
`id`obbligatorio	string (uuid)

InvitationResult

The answer of POST /v1/invitations and POST /v1/invitations/{id}/resend.

Campo	Tipo	Descrizione
`email`obbligatorio	InvitationEmail
`invitation`obbligatorio	InvitationRef
`member`obbligatorio	MemberDto

LevelContextDto

Which rules the single level of an aggregate list follows (FAZ2 §5 "Listelerde hangi kural").

Campo	Tipo	Descrizione
`kind`obbligatorio	string	`user` (a `userId` filter: that user's current team), `team` (a `teamId` filter) or `company`.
`teamId`	string (uuid) \| null

MeDto

GET /v1/me.

Campo	Tipo	Descrizione
`access`obbligatorio	AccessDto
`capabilities`obbligatorio	CapabilitiesDto
`effectiveTimeZone`obbligatorio	string
`membership`obbligatorio	MeMembership
`organization`obbligatorio	MeOrganization
`organizations`obbligatorio	OrganizationChoice[]
`session`	MeSession \| null
`user`obbligatorio	MeUser

MeMembership

The membership in the current organization.

Campo	Tipo	Descrizione
`id`obbligatorio	string (uuid)
`isTracked`obbligatorio	boolean
`joinedAt`	string \| null
`role`obbligatorio	string
`status`obbligatorio	string
`teamId`	string (uuid) \| null
`teamName`	string \| null
`timeZone`	string \| null
`viewerTeamIds`obbligatorio	string (uuid)[]

MeOrganization

The current organization.

Campo	Tipo	Descrizione
`defaultLocale`obbligatorio	string
`id`obbligatorio	string (uuid)
`name`obbligatorio	string
`slug`obbligatorio	string
`status`obbligatorio	string
`timeZone`obbligatorio	string

MeSession

The current session.

Campo	Tipo	Descrizione
`absoluteExpiresAt`obbligatorio	string
`amr`obbligatorio	string[]
`authTime`obbligatorio	string
`clientId`obbligatorio	string
`id`obbligatorio	string (uuid)
`idleExpiresAt`obbligatorio	string

MeUser

The person (GET /v1/me → user).

Campo	Tipo	Descrizione
`email`obbligatorio	string
`emailVerification`obbligatorio	EmailVerificationDto	The e-mail verification gate (owner decision 3 Oct 2026).
`emailVerified`obbligatorio	boolean
`fullName`	string \| null
`id`obbligatorio	string (uuid)
`locale`obbligatorio	string

MemberDto

A membership with its person (MemberDto).

Campo	Tipo	Descrizione
`createdAt`obbligatorio	string
`email`obbligatorio	string
`emailVerified`obbligatorio	boolean
`fullName`	string \| null
`id`obbligatorio	string (uuid)
`invitation`	MemberInvitationDto \| null
`isTracked`obbligatorio	boolean
`joinedAt`	string \| null
`locale`obbligatorio	string
`role`obbligatorio	string	`owner`, `admin`, `team_admin`, `manager`, `employee`.
`status`obbligatorio	string	`invited`, `active`, `suspended`, `left`.
`teamId`	string (uuid) \| null
`teamName`	string \| null
`timeZone`	string \| null
`unassignedManager`obbligatorio	boolean	A Manager with neither a team nor viewer teams (sees the whole company until assigned).
`userId`obbligatorio	string (uuid)
`viewerTeamIds`obbligatorio	string (uuid)[]

MemberInvitationDto

The invitation of an invited member.

Campo	Tipo	Descrizione
`emailStatus`	string \| null	`queued`, `sending`, `sent`, `failed`, `suppressed`, `not_configured`, `suppressed_reserved` (an RFC 2606 / RFC 6761 reserved domain, never e-mailed), or `null` before the first e-mail.
`expiresAt`obbligatorio	string
`id`obbligatorio	string (uuid)
`lastSentAt`obbligatorio	string
`sentCount`obbligatorio	integer (int32)

MemberPage

A page of members (OpenAPI).

Campo	Tipo	Descrizione
`items`obbligatorio	MemberDto[]
`nextCursor`	string \| null

MemberRefDto

A member as a reference (current row): the connecting Admin of a connection, the owner of a webhook endpoint.

Campo	Tipo	Descrizione
`active`obbligatorio	boolean	The membership is active and (for an endpoint or a tenant connection) still an Owner or Admin.
`name`	string \| null
`userId`obbligatorio	string (uuid)

NamedRefDto

A reference by id and display name (a client, a person, a task).

Campo	Tipo	Descrizione
`id`obbligatorio	string (uuid)
`name`obbligatorio	string

OrganizationChoice

One organization of the person (sec.user_memberships).

Campo	Tipo	Descrizione
`current`obbligatorio	boolean
`id`obbligatorio	string (uuid)
`name`obbligatorio	string
`role`obbligatorio	string
`selectable`obbligatorio	boolean	Can this session's sign-in method open it (design §4.5.3)?

PatchMember

PATCH /v1/members/{id}.

Campo	Tipo	Descrizione
`isTracked`	boolean \| null
`role`	string \| null	`admin`, `team_admin`, `manager` or `employee` (the Owner is only transferred).
`teamId`	string (uuid) \| null	Primary team; `null` removes it.
`timeZone`	string \| null	IANA zone of the membership; `null` follows the organization.
`viewerTeamIds`	string (uuid)[] \| null	Extra read-only teams (Manager and TeamAdmin only).

PatchTeam

PATCH /v1/teams/{id}.

Campo	Tipo	Descrizione
`description`	string \| null
`name`	string \| null

PeriodReportDto

GET /v1/reports/productivity.

Campo	Tipo	Descrizione
`from`obbligatorio	string (date)
`groupBy`obbligatorio	string
`levelContext`obbligatorio	LevelContextDto
`periods`obbligatorio	ReportPeriodDto[]
`subject`obbligatorio	ReportSubjectDto
`teams`obbligatorio	TeamPeriodsDto[]	Only for the company subject: every visible team over its current members.
`to`obbligatorio	string (date)
`totals`obbligatorio	ReportFiguresDto

PlanAbsenceDto

Campo	Tipo	Descrizione
`color`obbligatorio	string
`countsAsWorked`obbligatorio	boolean	`timeEffect == worked`.
`endTime`	string \| null
`half`	string \| null
`id`obbligatorio	string (uuid)
`startTime`	string \| null	Local start and end of an `hours` absence.
`status`obbligatorio	string	`approved` or `pending`.
`timeEffect`obbligatorio	string	`leave`, `worked` or `none`.
`typeKey`	string \| null
`typeName`	string \| null	`null` for a built-in type that was not renamed (the UI translates `typeKey`).
`unit`obbligatorio	string	`days`, `half_day` or `hours`.

PlanShiftDto

Campo	Tipo	Descrizione
`color`	string \| null
`end`obbligatorio	string (date-time)
`endTime`obbligatorio	string	Local end; before the start for a night shift.
`id`obbligatorio	string (uuid)
`location`obbligatorio	string
`minMinutes`obbligatorio	integer (int32)
`start`obbligatorio	string (date-time)
`startTime`obbligatorio	string	Local start (`HH:mm`, the shift's zone).

Problem

RFC 9457 problem details (application/problem+json).

Campo	Tipo	Descrizione
`action`	string \| null	Permission key of a 403 (`teams.create`).
`code`obbligatorio	string	Stable snake_case error code (catalog `error-codes.json`).
`detail`	string \| null
`errors`	FieldError[] \| null
`requiredPlan`	string \| null	Lowest plan that includes the feature (402 `feature_not_in_plan`).
`retryAfterSeconds`	integer (int32) \| null	Seconds to wait (429, 503; also the `Retry-After` header).
`status`obbligatorio	integer (int32)
`title`obbligatorio	string	English title of the code (clients translate `code`).
`traceId`	string \| null	W3C trace id of the request.
`type`obbligatorio	string	Help page of the error code: `https://workify360.com/help/errors/<code>/`.

ProjectAmountDto

The amounts of one currency (rates are applied per allocation day and layer).

Campo	Tipo	Descrizione
`billableMinor`obbligatorio	integer (int64)	The billable hours at their rate.
`costMinor`obbligatorio	integer (int64)	Every allocated hour at its rate.
`currency`obbligatorio	string

ProjectBudgetUsageDto

The use of a project's budget, all time.

Campo	Tipo	Descrizione
`budgetMinor`	integer (int64) \| null	`null` unless `costsIncluded`.
`budgetMinutes`	integer (int64) \| null
`kind`obbligatorio	string	`hours` or `amount`.
`projectId`obbligatorio	string (uuid)
`usedMinor`	integer (int64) \| null	The cost in the project's currency; `null` unless `costsIncluded`.
`usedMs`obbligatorio	integer (int64)
`usedRatio`	string \| null	Used / budget, 4 decimals (`null` for an amount budget without `costsIncluded`).

ProjectDto

A project.

Campo	Tipo	Descrizione
`access`obbligatorio	string	`everyone` or `members`.
`archived`obbligatorio	boolean
`budget`	BudgetDto \| null
`client`	NamedRefDto \| null
`code`	string \| null
`color`	string \| null
`createdAt`obbligatorio	string (date-time)
`currency`obbligatorio	string	The currency of the project's rates and amount budget.
`description`	string \| null
`endDate`	string (date) \| null
`id`obbligatorio	string (uuid)
`isBillable`obbligatorio	boolean
`memberCount`obbligatorio	integer (int64)
`myRole`	string \| null	The caller's role in the project team (`member`, `manager`), `null` outside it.
`name`obbligatorio	string
`permissions`obbligatorio	ProjectPermissionsDto
`spentMs`obbligatorio	integer (int64)	Every allocation of the project, all time.
`startDate`	string (date) \| null
`status`obbligatorio	string	`active`, `on_hold` or `completed`.
`taskCount`obbligatorio	integer (int64)
`updatedAt`obbligatorio	string (date-time)

ProjectPage

GET /v1/projects.

Campo	Tipo	Descrizione
`items`obbligatorio	ProjectDto[]
`nextCursor`	string \| null

ProjectPermissionsDto

What the caller may do with a project (decided from the current rows, §5.3).

Campo	Tipo	Descrizione
`archive`obbligatorio	boolean
`delete`obbligatorio	boolean	Only a project without time.
`edit`obbligatorio	boolean	The project's fields (Owners and Admins).
`manageMembers`obbligatorio	boolean	The team (an Admin or the project's manager; only an Admin changes managers).
`manageTasks`obbligatorio	boolean	Tasks (an Admin or the project's manager).
`track`obbligatorio	boolean	The caller may track time on it now.

ProjectRefDto

A project reference of an allocation.

Campo	Tipo	Descrizione
`color`	string \| null	`#RRGGBB`.
`id`obbligatorio	string (uuid)
`name`obbligatorio	string

ProjectReportDto

GET /v1/reports/projects.

Campo	Tipo	Descrizione
`budgets`obbligatorio	ProjectBudgetUsageDto[]
`costsIncluded`obbligatorio	boolean	The caller sees rates and amounts (`projects.costs.read`).
`from`obbligatorio	string (date)
`groupBy`obbligatorio	string[]
`rows`obbligatorio	ProjectReportRowDto[]
`to`obbligatorio	string (date)
`totals`obbligatorio	ProjectReportTotalsDto

ProjectReportKeysDto

The dimensions of a row (the ones not grouped by are null).

Campo	Tipo	Descrizione
`clientId`	string (uuid) \| null
`clientName`	string \| null
`date`	string (date) \| null	The allocation's local day (`groupBy` `day`).
`projectId`	string (uuid) \| null
`projectName`	string \| null
`taskId`	string (uuid) \| null
`taskName`	string \| null
`userId`	string (uuid) \| null
`userName`	string \| null

ProjectReportRowDto

One row of the project report.

Campo	Tipo	Descrizione
`allocatedMs`obbligatorio	integer (int64)
`amounts`	ProjectAmountDto[] \| null	`null` unless `costsIncluded`.
`billableMs`obbligatorio	integer (int64)
`keys`obbligatorio	ProjectReportKeysDto
`nonBillableMs`obbligatorio	integer (int64)
`productiveMs`	integer (int64) \| null	With `includeProductive` only.
`unratedMs`obbligatorio	integer (int64)	Time without any rate (it is left out of the amounts).

ProjectReportTotalsDto

The totals of the report.

Campo	Tipo	Descrizione
`allocatedMs`obbligatorio	integer (int64)
`amounts`	ProjectAmountDto[] \| null
`billableMs`obbligatorio	integer (int64)
`nonBillableMs`obbligatorio	integer (int64)
`productiveMs`	integer (int64) \| null
`unratedMs`obbligatorio	integer (int64)

ProjectRequest

POST /v1/projects; PUT /v1/projects/{id} sends the whole body.

Campo	Tipo	Descrizione
`access`	string \| null	`everyone` (default) or `members`.
`budget`	BudgetRequest \| null
`clientId`	string (uuid) \| null
`code`	string \| null	`[A-Za-z0-9._-]{1,32}`, unique among active projects.
`color`	string \| null	`#RRGGBB`.
`currency`	string \| null	`TRY`, `USD` or `EUR`; locked once the project has rates or invoice lines (409 `project_currency_locked`).
`description`	string \| null
`endDate`	string (date) \| null
`isBillable`	boolean \| null	Default true.
`name`	string \| null
`startDate`	string (date) \| null
`status`	string \| null	`active` (default), `on_hold` or `completed`.

ReportFiguresDto

Figures of a group of users over a period (sums raw, percentages the users' average, counters user-days).

Campo	Tipo	Descrizione
`absenceCreditMs`obbligatorio	integer (int64)
`absentDays`obbligatorio	integer (int32)
`activeMs`obbligatorio	integer (int64)
`activeUserCount`obbligatorio	integer (int32)
`effectivenessPct`	number (double) \| null
`idleMs`obbligatorio	integer (int64)
`lateDays`obbligatorio	integer (int32)
`leaveDays`obbligatorio	number (double)
`leftEarlyDays`obbligatorio	integer (int32)
`neutralMs`obbligatorio	integer (int64)
`offlineMs`obbligatorio	integer (int64)
`overtimeDays`obbligatorio	integer (int32)
`overtimeMs`obbligatorio	integer (int64)
`productiveMs`obbligatorio	integer (int64)
`productivityPct`	number (double) \| null
`targetMs`obbligatorio	integer (int64)
`unproductiveMs`obbligatorio	integer (int64)
`userCount`obbligatorio	integer (int32)
`workedMs`obbligatorio	integer (int64)

ReportPeriodDto

One period of a grouped report: its key and bounds, then the figures.

ReportScopeDto

What the caller can see (FAZ1 AccessPolicy.ScopeOf).

Campo	Tipo	Descrizione
`kind`obbligatorio	string	`company`, `teams` or `self`.
`teamIds`obbligatorio	string (uuid)[]	The visible teams of a `teams` scope, sorted; empty otherwise (company = all).
`unassignedFallback`obbligatorio	boolean	A Manager without teams who sees the whole company until assigned.

ReportSubjectDto

Whom a report is about.

Campo	Tipo	Descrizione
`id`	string (uuid) \| null
`kind`obbligatorio	string	`company`, `team` or `user`.
`name`	string \| null

RotatedWebhookSecretDto

RotatedWebhookSecretDto: the new signing secret, shown once.

Campo	Tipo	Descrizione
`previousSecretExpiresAt`obbligatorio	string	Until then deliveries carry both signatures.
`secret`obbligatorio	string	`whsec_<base64>`: shown once, never again.

ShiftBody

ShiftBody of POST /v1/shifts, the bulk items and PUT /v1/shifts/{id} (the whole body). Fields left null are filled from templateId.

Campo	Tipo	Descrizione
`breakMinutes`	integer (int32) \| null
`color`	string \| null
`date`	string (date) \| null
`endTime`	string \| null
`location`	string \| null
`minMinutes`	integer (int32) \| null	`null` = the template's, else duration − break.
`note`	string \| null
`startTime`	string \| null
`teamId`	string (uuid) \| null	Required for an open shift; ignored for an assigned one (the user's current team is written).
`templateId`	string (uuid) \| null
`userId`	string (uuid) \| null	`null` = an open shift.

ShiftDto

A shift: local fields, UTC instants, the caller's permissions.

Campo	Tipo	Descrizione
`breakMinutes`obbligatorio	integer (int32)
`color`	string \| null
`createdAt`obbligatorio	string (date-time)
`createdBy`obbligatorio	CalendarUserRefDto
`crossesMidnight`obbligatorio	boolean
`date`obbligatorio	string (date)
`durationMinutes`obbligatorio	integer (int32)
`end`obbligatorio	string (date-time)
`endTime`obbligatorio	string
`id`obbligatorio	string (uuid)
`location`obbligatorio	string
`minMinutes`obbligatorio	integer (int32)
`note`	string \| null
`open`obbligatorio	boolean	No user assigned.
`permissions`obbligatorio	ShiftPermissionsDto
`source`obbligatorio	string	`manual`, `template`, `copy` or `request`.
`start`obbligatorio	string (date-time)
`startTime`obbligatorio	string
`teamId`	string (uuid) \| null	Open shift: its team; assigned: the user's team when it was written.
`teamName`	string \| null
`templateId`	string (uuid) \| null
`templateName`	string \| null
`timeZone`obbligatorio	string
`updatedAt`obbligatorio	string (date-time)
`user`	CalendarUserRefDto \| null
`userId`	string (uuid) \| null	`null` for an open shift.

ShiftListDto

GET /v1/shifts (the shifts **starting** in the range).

Campo	Tipo	Descrizione
`items`obbligatorio	ShiftDto[]

ShiftPermissionsDto

Campo	Tipo	Descrizione
`canDelete`obbligatorio	boolean
`canEdit`obbligatorio	boolean
`canPickUp`obbligatorio	boolean
`canRequestSwap`obbligatorio	boolean

SummaryDto

The summary of the visible users over a range.

Campo	Tipo	Descrizione
`absenceCreditMs`obbligatorio	integer (int64)
`absentDays`obbligatorio	integer (int32)
`activeMs`obbligatorio	integer (int64)
`activeUserCount`obbligatorio	integer (int32)
`atWorkMs`obbligatorio	integer (int64)
`days`obbligatorio	DayTotalDto[]
`deletedMs`obbligatorio	integer (int64)
`domains`obbligatorio	DomainTotalDto[]	Top 10.
`effectivenessPct`	number (double) \| null	Average of the users' range Effectiveness % (inactive tracked users included).
`from`obbligatorio	string (date)
`holidayDays`obbligatorio	number (double)
`idleMs`obbligatorio	integer (int64)
`inactiveUsers`obbligatorio	UserTotalDto[]	Tracked users without activity in the range (zero totals, attendance fields), by user id.
`lateDays`obbligatorio	integer (int32)
`leaveDays`obbligatorio	number (double)
`leftEarlyDays`obbligatorio	integer (int32)
`levelContext`obbligatorio	LevelContextDto
`meetingMs`obbligatorio	integer (int64)
`neutralMs`obbligatorio	integer (int64)
`offlineMs`obbligatorio	integer (int64)
`overtimeMs`obbligatorio	integer (int64)
`privateMs`obbligatorio	integer (int64)
`productiveMs`obbligatorio	integer (int64)
`productivityPct`	number (double) \| null	Average of the users' range Productivity %.
`scope`obbligatorio	ReportScopeDto
`shiftDays`obbligatorio	integer (int32)
`teams`obbligatorio	TeamTotalDto[]	By current team: named teams by name, the `teamId: null` row last.
`to`obbligatorio	string (date)
`topApps`obbligatorio	AppTotalDto[]	Top 10; `name` is "Offline time" for the reserved offline keys.
`unproductiveMs`obbligatorio	integer (int64)
`users`obbligatorio	UserTotalDto[]	One row per user with a computed day in the range, by `activeMs`.
`workedMs`obbligatorio	integer (int64)

TargetItemDto

Campo	Tipo	Descrizione
`activeMs`obbligatorio	integer (int64)
`categoryKey`	string \| null
`categorySource`obbligatorio	string	`tenant`, `builtin` or `none`.
`domain`	string \| null
`level`obbligatorio	string
`levelSource`obbligatorio	string	`team`, `company` or `default`.
`matchedKey`	string \| null
`name`obbligatorio	string
`percentage`obbligatorio	number (double)
`targetKey`obbligatorio	string
`targetType`obbligatorio	string	`app` for apps, `domain` for domains and hosts.
`userCount`obbligatorio	integer (int32)

TargetListDto

The "Apps & URLs" list.

Campo	Tipo	Descrizione
`from`obbligatorio	string (date)
`items`obbligatorio	TargetItemDto[]	By active time descending, then key.
`levelContext`obbligatorio	LevelContextDto
`nextCursor`	string \| null
`to`obbligatorio	string (date)
`total`obbligatorio	integer (int32)	Targets matching the filters (before paging).
`totalActiveMs`obbligatorio	integer (int64)	Active time over every target of the type before the filters (the percentage base).
`type`obbligatorio	string	`app`, `domain` or `host`.

TaskDto

A task.

Campo	Tipo	Descrizione
`archived`obbligatorio	boolean
`assignee`	NamedRefDto \| null
`createdAt`obbligatorio	string (date-time)
`description`	string \| null
`dueDate`	string (date) \| null
`effectiveBillable`obbligatorio	boolean
`estimateMinutes`	integer (int64) \| null
`id`obbligatorio	string (uuid)
`isBillable`	boolean \| null	`null` takes the project's value.
`name`obbligatorio	string
`permissions`obbligatorio	TaskPermissionsDto
`projectId`obbligatorio	string (uuid)
`sortOrder`obbligatorio	integer (int64)
`spentMs`obbligatorio	integer (int64)
`status`obbligatorio	string	`open`, `in_progress` or `done`.
`updatedAt`obbligatorio	string (date-time)

TaskPage

GET /v1/projects/{id}/tasks.

Campo	Tipo	Descrizione
`items`obbligatorio	TaskDto[]
`nextCursor`	string \| null

TaskPermissionsDto

What the caller may do with a task.

Campo	Tipo	Descrizione
`delete`obbligatorio	boolean	Only a task without time.
`edit`obbligatorio	boolean

TaskRequest

POST /v1/projects/{id}/tasks; PUT /v1/tasks/{id} sends the whole body.

Campo	Tipo	Descrizione
`assigneeUserId`	string (uuid) \| null	Must be able to track time on the project (422 `project_not_trackable`).
`description`	string \| null
`dueDate`	string (date) \| null
`estimateMinutes`	integer (int64) \| null	1–1 000 000.
`isBillable`	boolean \| null	`null` takes the project's value.
`name`	string \| null
`sortOrder`	integer (int64) \| null
`status`	string \| null	`open` (default), `in_progress` or `done`.

TeamDto

A team with its size and leads (TeamDto).

Campo	Tipo	Descrizione
`archivedAt`	string \| null
`createdAt`obbligatorio	string
`description`	string \| null
`id`obbligatorio	string (uuid)
`leads`obbligatorio	object[]	TeamAdmins and Managers of the team: `[{membershipId, userId, fullName, role}]`.
`memberCount`obbligatorio	integer (int64)	Members whose primary team this is (left members excluded).
`name`obbligatorio	string
`updatedAt`obbligatorio	string

TeamPage

A page of teams (OpenAPI).

Campo	Tipo	Descrizione
`items`obbligatorio	TeamDto[]
`nextCursor`	string \| null

TeamPeriodsDto

Campo	Tipo	Descrizione
`periods`obbligatorio	ReportPeriodDto[]
`teamId`obbligatorio	string (uuid)
`teamName`	string \| null
`totals`obbligatorio	ReportFiguresDto

TeamTotalDto

One team row of a summary (current teams; percentages the members' average).

Campo	Tipo	Descrizione
`absenceCreditMs`obbligatorio	integer (int64)
`absentDays`obbligatorio	integer (int32)
`activeMs`obbligatorio	integer (int64)
`activeUserCount`obbligatorio	integer (int32)
`effectivenessPct`	number (double) \| null
`holidayDays`obbligatorio	number (double)
`idleMs`obbligatorio	integer (int64)
`lateDays`obbligatorio	integer (int32)
`leaveDays`obbligatorio	number (double)
`leftEarlyDays`obbligatorio	integer (int32)
`memberCount`obbligatorio	integer (int32)
`neutralMs`obbligatorio	integer (int64)
`offlineMs`obbligatorio	integer (int64)
`overtimeMs`obbligatorio	integer (int64)
`productiveMs`obbligatorio	integer (int64)
`productivityPct`	number (double) \| null
`shiftDays`obbligatorio	integer (int32)
`teamId`	string (uuid) \| null	`null` for the users without a team.
`teamName`	string \| null
`unproductiveMs`obbligatorio	integer (int64)
`workedMs`obbligatorio	integer (int64)

TimeEntryDecisionRequest

POST /v1/time-entries/{id}/decision.

Campo	Tipo	Descrizione
`decision`	string \| null	`approve` or `reject`.
`note`	string \| null	At most 500 characters.

TimeEntryDto

An offline entry or a deletion (design §8.2).

Campo	Tipo	Descrizione
`createdAt`obbligatorio	string (date-time)
`createdBy`obbligatorio	TimeEntryUserRefDto
`date`obbligatorio	string (date)	The user's local day of the entry, in the zone effective when it was written.
`decidedAt`	string (date-time) \| null
`decidedBy`	TimeEntryUserRefDto \| null
`decisionNote`	string \| null
`description`	string \| null
`durationMs`obbligatorio	integer (int64)
`end`obbligatorio	string (date-time)
`id`obbligatorio	string (uuid)
`kind`obbligatorio	string	`offline` or `deletion`.
`level`	string \| null	Offline: `productive`, `neutral` or `unproductive`; deletion: `null`.
`permissions`obbligatorio	TimeEntryPermissionsDto
`projectId`	string (uuid) \| null	Always `null` until projects (Phase 6).
`source`obbligatorio	string	`manual` (Phase 8 adds `calendar`).
`start`obbligatorio	string (date-time)
`status`obbligatorio	string	`pending`, `approved` or `rejected`.
`timeZone`obbligatorio	string
`updatedAt`obbligatorio	string (date-time)
`userId`obbligatorio	string (uuid)

TimeEntryPage

GET /v1/time-entries: by start.

Campo	Tipo	Descrizione
`items`obbligatorio	TimeEntryDto[]
`nextCursor`	string \| null

TimeEntryPermissionsDto

What the caller may do with the entry (TimeEntryPolicy.PermissionsFor), the same on every endpoint.

Campo	Tipo	Descrizione
`canApprove`obbligatorio	boolean
`canDelete`obbligatorio	boolean
`canEdit`obbligatorio	boolean

TimeEntryUserRefDto

A user reference of an entry (fullName from the directory; null when unknown).

Campo	Tipo	Descrizione
`fullName`	string \| null
`id`obbligatorio	string (uuid)

TimeIntervalDto

A UTC interval without any detail (e.g. a private interval).

Campo	Tipo	Descrizione
`end`obbligatorio	string (date-time)
`start`obbligatorio	string (date-time)

TimerAtRequest

POST /v1/me/timer/stop and /discard.

Campo	Tipo	Descrizione
`at`	string (date-time) \| null

TimerCommandResultDto

The result of a command (200 also when it did not apply).

Campo	Tipo	Descrizione
`applied`obbligatorio	boolean
`closed`obbligatorio	AllocationDto[]	The allocations written from the segment this command closed (may be empty).
`reason`	string \| null	`stale`, `not_running` or `unchanged`; `null` when applied.
`timer`obbligatorio	TimerDto

TimerDto

GET /v1/me/timer (ETag: "v<rowVersion>", "v0" before the first command).

Campo	Tipo	Descrizione
`autoStopAt`	string (date-time) \| null	`startedAt` + 24 hours.
`effectiveBillable`	boolean \| null
`isBillable`	boolean \| null
`last`	TimerLastDto \| null
`note`	string \| null
`project`	TimerProjectDto \| null
`segmentId`	string (uuid) \| null
`serverTime`obbligatorio	string (date-time)	The server's clock (clients compute the elapsed time against it).
`source`	string \| null	`web`, `desktop` or `api`.
`startedAt`	string (date-time) \| null
`state`obbligatorio	string	`running` or `stopped`.
`task`	NamedRefDto \| null

TimerLastDto

The segment that ended last.

Campo	Tipo	Descrizione
`endReason`obbligatorio	string	`stop`, `switch`, `autostop` or `discard`.
`endedAt`obbligatorio	string (date-time)
`segmentId`obbligatorio	string (uuid)
`startedAt`obbligatorio	string (date-time)

TimerProjectDto

The project of the running segment.

Campo	Tipo	Descrizione
`clientName`	string \| null
`color`	string \| null
`id`obbligatorio	string (uuid)
`name`obbligatorio	string

TimerStartRequest

POST /v1/me/timer/start (Idempotency-Key: the client's command id): start, or switch while running.

Campo	Tipo	Descrizione
`at`	string (date-time) \| null	The client's clock when the command was given (default: the server's now; at most 5 minutes ahead, at most 7 days back).
`isBillable`	boolean \| null
`note`	string \| null
`projectId`	string (uuid) \| null
`source`	string \| null	`web` (default), `desktop` or `api`.
`taskId`	string (uuid) \| null

UpdateTimeEntryRequest

PUT /v1/time-entries/{id}: the whole editable body (kind and user never change; If-Match instead of version).

Campo	Tipo	Descrizione
`description`	string \| null
`end`	string (date-time) \| null
`level`	string \| null
`projectId`	string (uuid) \| null
`start`	string (date-time) \| null

UpdateWebhookEndpointRequest

PATCH /v1/webhook-endpoints/{id} (If-Match).

Campo	Tipo	Descrizione
`description`	string \| null	`null` clears it.
`eventTypes`	string[] \| null
`status`	string \| null	`active` (also opens a `disabled` endpoint and resets its failure counters) or `paused`.
`takeOver`	boolean \| null	`true`: the caller becomes the endpoint's owner (lifts an `owner_inactive` pause).
`url`	string \| null

UserDailyDto

A user's days: computed days plus the workdays without activity up to the user's today.

Campo	Tipo	Descrizione
`days`obbligatorio	UserDayDto[]
`from`obbligatorio	string (date)
`teamId`	string (uuid) \| null	The user's current primary team (its rules classify every day).
`timeZone`obbligatorio	string
`to`obbligatorio	string (date)
`userId`obbligatorio	string (uuid)

UserDayDto

Campo	Tipo	Descrizione
`absence`	DayAbsenceDto \| null
`absenceCreditMs`obbligatorio	integer (int64)
`activeMs`obbligatorio	integer (int64)
`afkCoverage`obbligatorio	boolean
`arrivalAt`	string (date-time) \| null
`atWorkMs`obbligatorio	integer (int64)
`attendanceStatus`	string \| null	`onTime`, `late`, `absent`, `notStarted`, `dayOff`, `onLeave`, `holiday`; `null` outside the directory.
`classified`obbligatorio	boolean
`date`obbligatorio	string (date)
`dayOffWorkedMs`obbligatorio	integer (int64)
`deletedMs`obbligatorio	integer (int64)
`effectivenessPct`	number (double) \| null
`eventCount`obbligatorio	integer (int64)
`expectedWorkMs`obbligatorio	integer (int64)
`holiday`	DailyHolidayDto \| null
`idleMs`obbligatorio	integer (int64)
`lateByMs`obbligatorio	integer (int64)
`leftAt`	string (date-time) \| null
`leftEarly`obbligatorio	boolean
`leftEarlyByMs`obbligatorio	integer (int64)
`meetingMs`obbligatorio	integer (int64)
`neutralMs`obbligatorio	integer (int64)
`offlineMs`obbligatorio	integer (int64)
`overtimeMs`obbligatorio	integer (int64)
`planKind`	string \| null	`schedule`, `shift`, `dayOff` or `holiday`.
`privateMs`obbligatorio	integer (int64)
`productiveMs`obbligatorio	integer (int64)
`productivityPct`	number (double) \| null
`shiftCount`obbligatorio	integer (int32)
`targetMs`obbligatorio	integer (int64)
`topApp`	string \| null	Display name of the app with the most active time.
`unproductiveMs`obbligatorio	integer (int64)
`workday`	boolean \| null
`workedMs`obbligatorio	integer (int64)

UserTotalDto

One user of a summary.

Campo	Tipo	Descrizione
`absenceCreditMs`obbligatorio	integer (int64)
`absentDays`	integer (int32) \| null	Only for tracked users.
`activeDays`obbligatorio	integer (int32)	Local days with active time.
`activeMs`obbligatorio	integer (int64)
`arrivalAt`	string (date-time) \| null	Earliest arrival and latest leave in the range.
`atWorkMs`obbligatorio	integer (int64)
`classifiedDays`obbligatorio	integer (int32)
`dayOffWorkedMs`obbligatorio	integer (int64)
`deletedMs`obbligatorio	integer (int64)
`effectivenessPct`	number (double) \| null	`null` without a target and for users missing from the directory.
`email`	string \| null
`eventCount`obbligatorio	integer (int64)
`fullName`	string \| null
`holidayDays`obbligatorio	number (double)
`idleMs`obbligatorio	integer (int64)
`lateDays`	integer (int32) \| null
`leaveDays`obbligatorio	number (double)
`leftAt`	string (date-time) \| null
`leftEarlyDays`	integer (int32) \| null
`meetingMs`obbligatorio	integer (int64)
`neutralMs`obbligatorio	integer (int64)
`offlineMs`obbligatorio	integer (int64)
`overtimeDays`obbligatorio	integer (int32)
`overtimeMs`obbligatorio	integer (int64)
`privateMs`obbligatorio	integer (int64)
`productiveMs`obbligatorio	integer (int64)
`productivityPct`	number (double) \| null
`shiftDays`obbligatorio	integer (int32)
`targetMs`	integer (int64) \| null
`teamId`	string (uuid) \| null
`teamName`	string \| null
`timeZone`obbligatorio	string
`unproductiveMs`obbligatorio	integer (int64)
`userId`obbligatorio	string (uuid)
`workdays`	integer (int32) \| null
`workedMs`obbligatorio	integer (int64)

WebhookDeliveryDetailDto

GET /v1/webhook-endpoints/{id}/deliveries/{deliveryId}: the delivery and the body that was (or is) sent.

WebhookDeliveryDto

WebhookDeliveryDto.

Campo	Tipo	Descrizione
`attempts`obbligatorio	integer (int32)
`createdAt`obbligatorio	string
`deliveredAt`	string \| null
`eventId`obbligatorio	string (uuid)	The `webhook-id` header.
`eventType`obbligatorio	string
`id`obbligatorio	string	A 64-bit integer as a string.
`lastDurationMs`	integer (int32) \| null
`lastError`	string \| null	`timeout`, `connect`, `tls`, `not_allowed`, `http_<code>`, `not_in_plan`, `owner_inactive`.
`lastStatusCode`	integer (int32) \| null
`nextAttemptAt`	string \| null
`status`obbligatorio	string	`pending`, `succeeded`, `failed`, `dead`.

WebhookDeliveryPage

GET /v1/webhook-endpoints/{id}/deliveries (newest first).

Campo	Tipo	Descrizione
`items`obbligatorio	WebhookDeliveryDto[]
`nextCursor`	string \| null

WebhookEndpointDto

WebhookEndpointDto.

Campo	Tipo	Descrizione
`createdAt`obbligatorio	string
`description`	string \| null
`eventTypes`obbligatorio	string[]
`id`obbligatorio	string (uuid)
`owner`obbligatorio	MemberRefDto	The member who owns the endpoint (G1: a delivery needs an active Owner or Admin owner).
`previousSecretExpiresAt`	string \| null	After a rotation the previous secret still signs until then (24 hours).
`secretPrefix`obbligatorio	string	The first 8 characters of the signing secret (`whsec_Kx`); never the secret.
`stats`obbligatorio	WebhookEndpointStatsDto
`status`obbligatorio	string	`active`, `paused`, `disabled`.
`statusReason`	string \| null	`manual`, `owner_inactive`, `failing`, `gone`; `null` while active.
`updatedAt`obbligatorio	string
`url`obbligatorio	string
`version`obbligatorio	integer (int64)	`row_version` (`ETag: "v<n>"`, `If-Match` of `PATCH`).

WebhookEndpointPage

GET /v1/webhook-endpoints.

Campo	Tipo	Descrizione
`items`obbligatorio	WebhookEndpointDto[]
`nextCursor`	string \| null

WebhookEndpointStatsDto

The delivery statistics of an endpoint.

Campo	Tipo	Descrizione
`consecutiveFailures`obbligatorio	integer (int32)
`lastFailureAt`	string \| null
`lastSuccessAt`	string \| null

WebhookEventDto

One event type of GET /v1/webhook-events.

Campo	Tipo	Descrizione
`available`obbligatorio	boolean	The tenant's plan has the feature: an endpoint may subscribe.
`description`obbligatorio	string	One English sentence (the panel translates by `type`).
`feature`	string \| null	The plan feature the event needs (`null`: every plan with `api_access`).
`object`obbligatorio	string	The `data.object` of the delivery body.
`type`obbligatorio	string	`<object>.<verb>`, e.g. `time_entry.approved`.

WebhookEventsDto

GET /v1/webhook-events.

Campo	Tipo	Descrizione
`items`obbligatorio	WebhookEventDto[]

WebhookTestDto

202 of POST /v1/webhook-endpoints/{id}/test.

Campo	Tipo	Descrizione
`deliveryId`obbligatorio	string	The delivery of the test event (a string: the deliveries' id is a 64-bit integer).

Riferimento dell'API pubblica

Autenticazione

Scope

Limiti di frequenza

Errori

Webhook

Operazioni

Assenze

GET /v1/absences Scope: reports:read

Parametri

POST /v1/absences Scope: time:write

Parametri

POST /v1/absences/{id}/decision Scope: time:write

Parametri

Attività

GET /v1/activity/day Scope: reports:read

Parametri

Assegnazioni del tempo

GET /v1/allocations Scope: reports:read

Parametri

POST /v1/allocations Scope: time:write

Parametri

Esportazioni

POST /v1/exports Scope: reports:read

Parametri

GET /v1/exports/{id} Scope: reports:read

Parametri

Il mio profilo

GET /v1/me Scope: me

Membri

POST /v1/invitations Scope: org:admin

Parametri

GET /v1/members Scope: org:admin

Parametri

GET /v1/members/{id} Scope: org:admin

Parametri

PATCH /v1/members/{id} Scope: org:admin

Parametri

POST /v1/members/{id}/reactivate Scope: org:admin

Parametri

POST /v1/members/{id}/suspend Scope: org:admin

Parametri

Progetti

GET /v1/projects Scope: reports:read

Parametri

POST /v1/projects Scope: org:admin

Parametri

GET /v1/projects/{id} Scope: reports:read

Parametri

PUT /v1/projects/{id} Scope: org:admin

Parametri

Report

GET /v1/reports/productivity Scope: reports:read

Parametri

GET /v1/reports/projects Scope: reports:read

Parametri

GET /v1/reports/summary Scope: reports:read

Parametri

GET /v1/reports/targets Scope: reports:read

Parametri

GET /v1/reports/users/{userId}/daily Scope: reports:read

Parametri

Turni

GET /v1/shifts Scope: reports:read

Parametri

POST /v1/shifts Scope: time:write

Parametri

Task

GET /v1/projects/{id}/tasks Scope: reports:read

Parametri

POST /v1/projects/{id}/tasks Scope: time:write

Parametri

GET /v1/tasks/{id} Scope: reports:read

Parametri

PUT /v1/tasks/{id} Scope: time:write

Parametri

Team

GET /v1/teams Scope: reports:read

Parametri

POST /v1/teams Scope: org:admin

GET `/v1/absences` Scope: `reports:read`

POST `/v1/absences` Scope: `time:write`

POST `/v1/absences/{id}/decision` Scope: `time:write`

GET `/v1/activity/day` Scope: `reports:read`

GET `/v1/allocations` Scope: `reports:read`

POST `/v1/allocations` Scope: `time:write`

POST `/v1/exports` Scope: `reports:read`

GET `/v1/exports/{id}` Scope: `reports:read`

GET `/v1/me` Scope: `me`

POST `/v1/invitations` Scope: `org:admin`

GET `/v1/members` Scope: `org:admin`

GET `/v1/members/{id}` Scope: `org:admin`

PATCH `/v1/members/{id}` Scope: `org:admin`

POST `/v1/members/{id}/reactivate` Scope: `org:admin`

POST `/v1/members/{id}/suspend` Scope: `org:admin`

GET `/v1/projects` Scope: `reports:read`

POST `/v1/projects` Scope: `org:admin`

GET `/v1/projects/{id}` Scope: `reports:read`

PUT `/v1/projects/{id}` Scope: `org:admin`

GET `/v1/reports/productivity` Scope: `reports:read`

GET `/v1/reports/projects` Scope: `reports:read`

GET `/v1/reports/summary` Scope: `reports:read`

GET `/v1/reports/targets` Scope: `reports:read`

GET `/v1/reports/users/{userId}/daily` Scope: `reports:read`

GET `/v1/shifts` Scope: `reports:read`

POST `/v1/shifts` Scope: `time:write`

GET `/v1/projects/{id}/tasks` Scope: `reports:read`

POST `/v1/projects/{id}/tasks` Scope: `time:write`

GET `/v1/tasks/{id}` Scope: `reports:read`

PUT `/v1/tasks/{id}` Scope: `time:write`

GET `/v1/teams` Scope: `reports:read`

POST `/v1/teams` Scope: `org:admin`

PATCH `/v1/teams/{id}` Scope: `org:admin`

GET `/v1/time-entries` Scope: `reports:read`

POST `/v1/time-entries` Scope: `time:write`

GET `/v1/time-entries/{id}` Scope: `reports:read`

PUT `/v1/time-entries/{id}` Scope: `time:write`

DELETE `/v1/time-entries/{id}` Scope: `time:write`

POST `/v1/time-entries/{id}/decision` Scope: `time:write`

GET `/v1/me/timer` Scope: `me`

POST `/v1/me/timer/start` Scope: `me`

POST `/v1/me/timer/stop` Scope: `me`

GET `/v1/webhook-endpoints` Scope: `webhooks:manage`

POST `/v1/webhook-endpoints` Scope: `webhooks:manage`

GET `/v1/webhook-endpoints/{id}` Scope: `webhooks:manage`

PATCH `/v1/webhook-endpoints/{id}` Scope: `webhooks:manage`

DELETE `/v1/webhook-endpoints/{id}` Scope: `webhooks:manage`

GET `/v1/webhook-endpoints/{id}/deliveries` Scope: `webhooks:manage`

GET `/v1/webhook-endpoints/{id}/deliveries/{deliveryId}` Scope: `webhooks:manage`

POST `/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry` Scope: `webhooks:manage`

POST `/v1/webhook-endpoints/{id}/rotate-secret` Scope: `webhooks:manage`

POST `/v1/webhook-endpoints/{id}/test` Scope: `webhooks:manage`

GET `/v1/webhook-events` Scope: `webhooks:manage`