Tyme Public API Documentation

To get access to the API, please drop us a message.

  • API Endpoint: https://api.tyme-app.com
  • All dates & times exchanged in GMT+0.
  • Date Format: Y-m-d H:i:s Example: 2025-12-31 23:59:59
  • The exchange format is JSON.
  • You need to have a team and be a team admin. You can create a new team in Tyme > File > Login > Create Team.

Authentication

Tyme uses the OAuth v2 standard for authenticating users. To make yourself familiar with OAuth, please take a look at the rfc6749.

Auth Endpoint

Login form to log the user in and redirect them to your app

GET /v1/authorize
Parameter Type Description
response_type String Must be code
client_id String Your client ID
state String Your state
redirect_uri String Your redirect_uri

Access Token Endpoint

Exchange the authcode with an access & refresh token

POST /v1/access_token
Parameter Type Description
grant_type String Must be authorization_code
code String Your auth code
redirect_uri String Your redirect_uri
client_id String Your client ID
client_secret String Your client secret

Refresh Token Endpoint

Exchange the refresh token with a new access & refresh token

POST /v1/refresh_token
Parameter Type Description
grant_type String Must be refresh_token
refresh_token String Your refresh token
client_id String Your client ID
client_secret String Your client secret

Bidirectional Sync

POST /v1/sync

Tyme offers a full bidirectional sync. Based on a revision, the API delivers only the changes you've not yet received. After each call to the sync endpoint, store the new revision and send it along with the next request.

Parameter Type Description
project_updates Array Category, project or task data, that should be updated
project_deletions Array Time entry data that should be updated
time_updates Array Category, project or task IDs that should be deleted
time_deletions Array Time entry IDs that should be deleted
revision String Initial revision: 1.1.1.1

Webhooks

You can use webhooks to subscribe for realtime notifications. The following notifications are available:

  • New category created
  • New project created
  • New task created
  • New sub-task created
  • New time entry created
  • Stopped time entry

Subscribing to a webhook

POST /webhooks/subscribe
Parameter Type Description
hook_url String The URL that should be called from the webhook
trigger_type String category, project, task, subtask, time or stopped_time

Response

Status Code Parameter Value
200 status success
403 error not_allowed
400 error missing values

Your response when your webhook is called

Status Code Description
200 OK
410 Webhook subscription inactive, stop sending data

Webhook Example POST output

[
  {
    "id": "D16DB305-DACB-471E-833F-29330C913E45-46205-00000AB867F3D867",
    "team_id": "5881f10158f36",
    "modified": "2024-04-26 11:25:21",
    "created": "2024-07-18 08:25:32",
    "user_id": "5881f10158f22",
    "related_id": "FE323534-642E-44BC-9EA8-F1F92146D626-46205-00000AAF8E02124C",
    "type": "TimedTaskRecord",
    "time_start": "2017-04-26 10:25:00",
    "time_end": "2017-04-26 11:25:00",
    "billing_state": 0,
    "note": "",
    "task_id": "FE323534-642E-44BC-9EA8-F1F92146D626-46205-00000AAF8E02124C",
    "task_name": "Eine Aufgabe",
    "duration": 3600,
    "duration_rounded": 3600,
    "revenue": 100,
    "project_id": "AEA5BFD8-06E5-43AD-9B4F-DECB15143176-46205-00000AA8CBE4B44B",
    "project_name": "New Project",
    "category_id": "t199489890",
    "category_name": "Category",
    "full_name": "Category: New Project: Eine Aufgabe"
  },
  {
    "id": "AEA5BFD8-06E5-43AD-9B4F-DECB15143176-46205-00000AA8CBE4B44B",
    "team_id": "5881f10158f36",
    "modified": "2024-04-26 11:25:59",
    "related_id": "t199489890",
    "type": "Project",
    "hourly_rate": 0,
    "rounding_method": 1,
    "rounding_minutes": 1,
    "default_hourly_rate": 100,
    "name": "New Project",
    "planned_budget": 0,
    "planned_duration": 36000,
    "created_date": "2024-04-26 11:24:03",
    "color": 10342999,
    "billable": 1,
    "fixed_rate": 0,
    "quantity": 0,
    "start_date": null,
    "due_date": null,
    "kilometer_rate": 0,
    "completed_date": null,
    "tracking_mode": 0,
    "modifier_flags": 0,
    "recurring_period": 0,
    "note": null,
    "cached_total": 0,
    "project_id": "AEA5BFD8-06E5-43AD-9B4F-DECB15143176-46205-00000AA8CBE4B44B",
    "project_name": "New Project",
    "category_id": "t199489890",
    "category_name": "Category",
    "full_name": "Category: New Project"
  }
]

Unsubscribing from a webhook

POST /webhooks/unsubscribe
Parameter Type Description
hook_url String The URL that should be called from the webhook
trigger_type String category, project task, subtask, time or stopped_time

Response

Status Code Parameter Value
200 status success
403 error not_allowed
400 error missing values

Searching for entities

GET /data/search_entity
Parameter Type Description
type String ProjectCategory, Project ,TimedTask or TimedSubTask
name String? Name to search for
parent_id String? ID of the parent entity. For example a project ID when searching for a task

Response

Status Code Parameter Value
200 Array found results
403 error not_allowed
400 error missing values

Results

{
  "id": "tsub67891",
  "team_id": "5881f10158f36",
  "modified": "2024-03-21 08:13:11",
  "related_id": "t1234567891",
  "type": "TimedSubTask",
  "hourly_rate": 75,
  "rounding_method": 1,
  "rounding_minutes": 30,
  "default_hourly_rate": 0,
  "name": "subtask of task1",
  "planned_budget": 0,
  "planned_duration": 0,
  "created_date": "2024-04-20 13:33:59",
  "color": 0,
  "billable": 1,
  "fixed_rate": 0,
  "quantity": 0,
  "start_date": null,
  "due_date": null,
  "kilometer_rate": 0,
  "completed_date": "2024-04-20 13:33:59",
  "tracking_mode": 0,
  "modifier_flags": 0,
  "recurring_period": 0,
  "note": null,
  "cached_total": 0,
  "subtask_id": "tsub67891",
  "subtask_name": "subtask of task1",
  "task_id": "t1234567891",
  "task_name": "task1",
  "project_id": "t1234567890",
  "project_name": "project",
  "category_id": "AAF8E02-BFD8-06E5-43AD-9B4F-DECB15143176",
  "category_name": "category",
  "full_name": "category: project: task1: subtask of task1"
}

Inserting & Updating

POST /data/update_entity

Category

Parameter Type Description
type String Must be ProjectCategory
id String? ID of the category. If not provided, Tyme will generate a unique ID
name String Name of the category
color Int? i.e 0xFF9900

Project

Parameter Type Description
type String Must be Project
id String? ID of the project. If not provided, Tyme will generate a unique ID
name String Name of the project
color Int? i.e 0xFF9900
category_id String? ID of the parent category
rounding_method Int DOWN, NEAREST or UP
rounding_minutes Int Minutes the rounding is applied
hourly_rate Int Hourly Rate
planned_duration Int Duration in seconds
planned_budget Float Budget

Task

Parameter Type Description
type String Must be TimedTask
id String? ID of the task. If not provided, Tyme will generate a unique ID
name String Name of the task
project_id String? ID of the parent project
billable Bool Whether the task is billable or not
planned_duration Int Duration in seconds

Sub-Task

Parameter Type Description
type String Must be TimedSubTask
id String? ID of the sub-task. If not provided, Tyme will generate a unique ID
name String Name of the sub-task
task_id String? ID of the parent task
planned_duration Int Duration in seconds

Time Entry

Parameter Type Description
type String Must be TimedTaskRecord
id String? ID of the time entry. If not provided, Tyme will generate a unique ID
task_id String? ID of the parent task
time_start DateTime Start time
time_end DateTime? End time. Set to null if the time entry is still running
note String Note of the time entry
user_id String? User ID the entry belongs to

Absence

Parameter Type Description
type String Must be NonWorkingRecord
subtype Int vacation=0, sick=1, other=2, publicHoliday=3, overtimeCompensation=4, specialLeave=5
id String? ID of the entry. If not provided, Tyme will generate a unique ID
time_start DateTime Start time
time_end DateTime? End time
note String Note
user_id String? User ID the entry belongs to

Response

Status Code Parameter Value
200 status success
403 error not_allowed
400 error missing values

Deleting

DELETE /data/entity
Parameter Type Description
project_ids Array Array of entity ids (can be a project, task, sub-task, etc.)
time_ids Array Array of time entry ids

Response

Status Code Parameter Value
200 status success
403 error not_allowed

Task Summary

GET /data/summary
Parameter Type Description
from DateTime Start of the time frame
to DateTime End of the time frame

Response

Status Code Parameter Value
200 summary summary data
403 error not_allowed
400 error date_range_too_large

Summary Data Response

{
  "summary": [
    {
      "id": "FE323534-642E-44BC-9EA8-F1F92146D626-46205-00000AAF8E02124C",
      "type": "TimedTask",
      "name": "Some Task",
      "full_name": "Category: New Project: Some Task",
      "category_name": "Category",
      "category_id": "AAF8E02-BFD8-06E5-43AD-9B4F-DECB15143176",
      "project_name": "New Project",
      "project_id": "AEA5BFD8-06E5-43AD-9B4F-DECB15143176-46205-00000AA8CBE4B44B",
      "task_name": "Eine Aufgabe",
      "task_id": "FE323534-642E-44BC-9EA8-F1F92146D626-46205-00000AAF8E02124C",
      "subtask_name": null,
      "subtask_id": null,
      "time": 3600,
      "revenue": 100
    }
  ]
}

Get Team Members

GET /data/members/:user_id
Parameter Type Description
user_id String? Use me for yourself. Omit for all users

Response

Status Code Parameter Value
200 data user data
403 error not_allowed
400 error missing values

User Data Response

{
  "data": [
    {
      "id": "t123897987987",
      "team_id": "5881f10158f36",
      "name": "Hans",
      "email": "some@email.de",
      "role": 0,
      "working_times": "0,28800,28800,28800,28800,28800,0",
      "historic_working_times": null,
      "last_sync": "2017-01-20 14:00:49",
      "created": "2017-01-20 14:00:49",
      "assigned": []
    }
  ]
}

Get Times

GET /data/times
Parameter Type Description
from DateTime Start of the time frame
to DateTime End of the time frame
start Int? Paging start parameter
user_id String? Filter by user
billing_state Int? Filter by billing state (0=unbilled, 1=billed, 2=paid)

Response

Status Code Parameter Value
200 data times data
403 error not_allowed
400 error missing values

Times Response Data

{
  "data": [
    {
      "id": "D16DB305-DACB-471E-833F-29330C913E45-46205-00000AB867F3D867",
      "team_id": "5881f10158f36",
      "modified": "2024-04-26 11:25:21",
      "created": "2024-07-18 08:43:24",
      "user_id": "5881f10158f22",
      "related_id": "FE323534-642E-44BC-9EA8-F1F92146D626-46205-00000AAF8E02124C",
      "type": "TimedTaskRecord",
      "locked": 0,
      "subtype": 0,
      "traveled_distance": 0,
      "time_start": "2024-04-26 10:25:00",
      "time_end": "2024-04-26 11:25:00",
      "billing_state": 0,
      "note": "",
      "task_id": "FE323534-642E-44BC-9EA8-F1F92146D626-46205-00000AAF8E02124C",
      "task_name": "A Task",
      "duration": 3600,
      "duration_rounded": 3600,
      "revenue": 100,
      "project_id": "AEA5BFD8-06E5-43AD-9B4F-DECB15143176-46205-00000AA8CBE4B44B",
      "project_name": "New Project",
      "category_id": "AAF8E02-BFD8-06E5-43AD-9B4F-DECB15143176",
      "category_name": "Category",
      "full_name": "Category: New Project: A Task"
    }
  ],
  "start": 0,
  "limit": 500,
  "total": 11
}

4.7

Whether you're on your own or in a team, Tyme makes time tracking effortless. Actively developed for over 10 years and trusted by more than 50,000 happy users. With direct support from our developer team.

Start with a 14-day free trial.
Get Tyme

Tyme

PricingBlogRelease NotesPluginsDeveloper APIAbout Us

Topics

Getting Started with TymeTime Tracking as a TeamShortcuts for iPhone & MacInvoices with GrandTotalInvoices with Lexware OfficeInvoices with sevdesk

Service

Help & SupportImprintPrivacyContact
© 2025 Tyme – Made with 🧡 in Hamburg, Germany
Deutsch