NAV
cURL

Introduction

Welcome! This document provides a full list of all Timely APIs currently available, so you can start integrating Timely with your favorite applications.

Got questions? Please send them to support@timelyapp.com.

Authentication

OAuth2 Authentication: http://tools.ietf.org/html/rfc6749

Create an OAuth Application (only available to the Admin User): https://app.timelyapp.com/:account_id/oauth_applications

Enter your application name and the redirect_url to your application.

Acquire the Application Id and Secret.

The base URL for all API's is: https://api.timelyapp.com/1.1

Authorization

OAuth Code

Example Request: (try this in your web browser)
https://api.timelyapp.com/1.1/oauth/authorize?response_type=code
&redirect_uri=your_redirect_uri&client_id=your_client_id

Users are redirected to request their Timely identity.

HTTP Request

GET /oauth/authorize

Compulsory Parameters

Parameter Description
response_type code
redirect_uri http://your-redirect-url/
client_id your_application_id

If the user accepts your request, Timely will redirect back with the code parameter, which you need to use to get the token.

OAuth Token

Example Request:
curl -X POST --data "redirect_uri=https://your-redirect_url/&code=your_response_code
&client_id=application_id&client_secret=application_secret&grant_type=authorization_code"
https://api.timelyapp.com/1.1/oauth/token

{
  "access_token":"1886f011cd72eabc88d087eabd741b51a9059f5ba57c7bc439285fe86a4e465a",
  "token_type":"bearer",
  "refresh_token":"9db4d1a5d87c707b8125d8f93ad08091fb3ff8b93be901dbeaba968cf532ed9b"
}

200 OK

Users are redirected to request their Timely identity.

HTTP Request

POST /oauth/token

Compulsory Parameters

Parameter Description
redirect_uri http://your-redirect-url/
code your_response_code
client_id your_application_id
client_secret your_application_secret
grant_type authorization_code

The response will be a token with a refresh token. Use the token to use the following API.

Use Timely API to integrate with your apps

Timely API helps you integrate your application with Timely. Following are the list of API’s available. For any help or support email support@timelyapp.com

Accounts

List all accounts

Returns all the accounts created against one email address.

Request

curl -g "https://api.timelyapp.com/1.1/accounts" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer vH_C6F60pihBMl4nrzuTmJs60CbJZHK2qqP2E4SRaOk" \
    -H "Cookie: "

Endpoint

GET /1.1/accounts

GET /1.1/accounts
Accept: application/json
Content-Type: application/json
Authorization: Bearer vH_C6F60pihBMl4nrzuTmJs60CbJZHK2qqP2E4SRaOk

Parameters

None known.

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 18,
    "name": "Timely",
    "color": "44505e",
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "logo": {
      "large_retina": "/assets/account_thumbs/account_large_retina-8bc212c450af14b3a0ea49098cdddbe4f90d5eb5fc57adfeade6ac1ad8fb1d4a.png",
      "medium_retina": "/assets/account_thumbs/account_medium_retina-10dfbcc6733ccba1d485971f63c5eb7f9b7ed1a942a0ebd140e292bcb1e4dbea.png",
      "small_retina": "/assets/account_thumbs/account_small_retina-ea5df153b4cd96fc801e2361afc7d1b06d7b95ce5c358250b81149e1a20689df.png",
      "brand_logo": false
    },
    "from": "Web",
    "max_users": 0,
    "seats": 1,
    "max_projects": 0,
    "plan_id": 18,
    "plan_name": "Essential",
    "next_charge": "2025-04-13",
    "start_of_week": 0,
    "created_at": 1741851927,
    "payment_mode": "web",
    "paid": true,
    "company_size": "10-49",
    "plan_code": "essential",
    "plan_custom": false,
    "appstore_transaction_id": null,
    "owner_id": 40,
    "weekly_user_capacity": 40.0,
    "default_work_days": "MON,TUE,WED,THU,FRI",
    "default_hour_rate": 0.0,
    "support_email": "support@timelyapp.com",
    "estimated_company_size": null,
    "industry": null,
    "memory_retention_days": 0,
    "tic_force_enable": false,
    "num_users": 1,
    "num_projects": 0,
    "active_projects_count": 0,
    "total_projects_count": 0,
    "capacity": {
      "hours": 40,
      "minutes": 0,
      "seconds": 0.0,
      "formatted": "40:00",
      "total_hours": 40.0,
      "total_seconds": 144000.0,
      "total_minutes": 2400.0
    },
    "status": "active",
    "beta": false,
    "azure_ad_enabled": true,
    "expired": false,
    "trial": false,
    "days_to_end_trial": 0,
    "features": [
      {
        "name": "api_access",
        "days": -1
      },
      {
        "name": "control",
        "days": -1
      },
      {
        "name": "memories",
        "days": -1
      },
      {
        "name": "billing",
        "days": -1
      },
      {
        "name": "project_required_fields",
        "days": -1
      },
      {
        "name": "teams",
        "days": -1
      },
      {
        "name": "recurring_budget",
        "days": -1
      },
      {
        "name": "notifications_project_budget",
        "days": -1
      },
      {
        "name": "weekly_user_capacity",
        "days": -1
      },
      {
        "name": "company_view",
        "days": -1
      },
      {
        "name": "anomalies",
        "days": -1
      },
      {
        "name": "log_hours_for_others",
        "days": -1
      },
      {
        "name": "project_budget",
        "days": -1
      },
      {
        "name": "budgets_hourly_rates",
        "days": -1
      },
      {
        "name": "account_branding",
        "days": -1
      },
      {
        "name": "team_lead",
        "days": -1
      },
      {
        "name": "ai_timesheet_creation",
        "days": -1
      },
      {
        "name": "in_app_support",
        "days": -1
      },
      {
        "name": "people_dashboard",
        "days": -1
      },
      {
        "name": "people_notify",
        "days": -1
      },
      {
        "name": "premium_integrations",
        "days": -1
      },
      {
        "name": "individual_capacity",
        "days": -1
      },
      {
        "name": "audits",
        "days": -1
      },
      {
        "name": "project_dashboard",
        "days": -1
      },
      {
        "name": "high_level_reports",
        "days": -1
      },
      {
        "name": "live_reports",
        "days": -1
      },
      {
        "name": "invoices",
        "days": -1
      },
      {
        "name": "planned_entries",
        "days": -1
      },
      {
        "name": "internal_costs",
        "days": -1
      },
      {
        "name": "memory_retention",
        "days": -1
      },
      {
        "name": "custom_project_currencies",
        "days": -1
      },
      {
        "name": "capacity_reports",
        "days": -1
      },
      {
        "name": "day_locking",
        "days": -1
      },
      {
        "name": "user_custom_properties",
        "days": -1
      },
      {
        "name": "tasks",
        "days": -1
      },
      {
        "name": "planning",
        "days": -1
      },
      {
        "name": "batch_log_planned_time",
        "days": -1
      },
      {
        "name": "ai_labels_suggestions",
        "days": -1
      },
      {
        "name": "integration_monday",
        "days": -1
      },
      {
        "name": "hour_states",
        "days": -1
      },
      {
        "name": "tic_integrations",
        "days": -1
      },
      {
        "name": "tic_support",
        "days": -1
      },
      {
        "name": "import_manager",
        "days": -1
      }
    ]
  }
]

Retrieve activities

This endpoint shows you all activities tied to you and/or any other users you have permission to view. Activities include: logged hours, created a report, shared a report.

Request

curl -g "https://api.timelyapp.com/1.1/16/activities" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer aNif-ga_S9TZ0goKnx-2H_Lr0M0vqSs6QrIUMZ4Z6tc" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/activities

GET /1.1/16/activities
Accept: application/json
Content-Type: application/json
Authorization: Bearer aNif-ga_S9TZ0goKnx-2H_Lr0M0vqSs6QrIUMZ4Z6tc

Parameters

Name Description
account_id The ID of the account you want to retrieve
limit Retrieve a limited number of activities
offset Retrieve activities from offset
order Sorting order on created_at
filter Filter activities by entity_type - Ex: filter=projects

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 2,
    "user": {
      "id": 35,
      "email": "marijallkvydhy@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2025-03-13T08:45:26+01:00"
    },
    "message": "archived",
    "activity_type": "archive_project",
    "url": "http://app.timelyapp.local:3002/16/projects/11?type=archived_project",
    "updated_at": "2025-03-06T08:45:26+01:00",
    "detail": null,
    "associated_ids": [],
    "entity_type": "Project",
    "entity_deleted": false,
    "parent_entity_name": "",
    "entity": {
      "id": 11,
      "active": true,
      "name": "Timely",
      "color": "67a3bc",
      "client": {
        "id": 11,
        "name": "Soluta saepe quae omnis.",
        "color": "ffb74d",
        "active": true,
        "external_id": null,
        "updated_at": "2025-03-13T08:45:26+01:00"
      },
      "updated_at": "2025-03-13T08:45:26+01:00"
    },
    "anomaly": false
  },
  {
    "id": 1,
    "user": {
      "id": 35,
      "email": "marijallkvydhy@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/669656c40c201529ece28b7b41fbc085?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2025-03-13T08:45:26+01:00"
    },
    "message": "50% of budget used",
    "activity_type": "project_budget_progress_fifty",
    "url": "http://app.timelyapp.local:3002/16/projects/11?type=budget_progress",
    "updated_at": "2025-03-13T08:45:26+01:00",
    "detail": null,
    "associated_ids": [],
    "entity_type": "Project",
    "entity_deleted": false,
    "parent_entity_name": "",
    "entity": {
      "id": 11,
      "active": true,
      "name": "Timely",
      "color": "67a3bc",
      "client": {
        "id": 11,
        "name": "Soluta saepe quae omnis.",
        "color": "ffb74d",
        "active": true,
        "external_id": null,
        "updated_at": "2025-03-13T08:45:26+01:00"
      },
      "updated_at": "2025-03-13T08:45:26+01:00"
    },
    "anomaly": false
  }
]

Retrieve an account

Returns one account object related to one company and one subscription plan.

Request

curl -g "https://api.timelyapp.com/1.1/accounts/17" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer kz7r6irhsEvMBvihAHgQ-tLeE7-avd1YPXoQrjRVqns" \
    -H "Cookie: "

Endpoint

GET /1.1/accounts/:id

GET /1.1/accounts/17
Accept: application/json
Content-Type: application/json
Authorization: Bearer kz7r6irhsEvMBvihAHgQ-tLeE7-avd1YPXoQrjRVqns

Parameters

Name Description
id The id of the account to be retrieved

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 17,
  "name": "Timely",
  "color": "44505e",
  "currency": {
    "id": "usd",
    "name": "United States Dollar",
    "iso_code": "USD",
    "symbol": "$",
    "symbol_first": true
  },
  "logo": {
    "large_retina": "/assets/account_thumbs/account_large_retina-8bc212c450af14b3a0ea49098cdddbe4f90d5eb5fc57adfeade6ac1ad8fb1d4a.png",
    "medium_retina": "/assets/account_thumbs/account_medium_retina-10dfbcc6733ccba1d485971f63c5eb7f9b7ed1a942a0ebd140e292bcb1e4dbea.png",
    "small_retina": "/assets/account_thumbs/account_small_retina-ea5df153b4cd96fc801e2361afc7d1b06d7b95ce5c358250b81149e1a20689df.png",
    "brand_logo": false
  },
  "from": "Web",
  "max_users": 0,
  "seats": 1,
  "max_projects": 0,
  "plan_id": 17,
  "plan_name": "Essential",
  "next_charge": "2025-04-13",
  "start_of_week": 0,
  "created_at": 1741851927,
  "payment_mode": "web",
  "paid": true,
  "company_size": "10-49",
  "plan_code": "essential",
  "plan_custom": false,
  "appstore_transaction_id": null,
  "owner_id": 38,
  "weekly_user_capacity": 40.0,
  "default_work_days": "MON,TUE,WED,THU,FRI",
  "default_hour_rate": 0.0,
  "support_email": "support@timelyapp.com",
  "estimated_company_size": null,
  "industry": null,
  "memory_retention_days": 0,
  "tic_force_enable": false,
  "num_users": 1,
  "num_projects": 0,
  "active_projects_count": 0,
  "total_projects_count": 0,
  "capacity": {
    "hours": 40,
    "minutes": 0,
    "seconds": 0.0,
    "formatted": "40:00",
    "total_hours": 40.0,
    "total_seconds": 144000.0,
    "total_minutes": 2400.0
  },
  "status": "active",
  "beta": false,
  "azure_ad_enabled": true,
  "expired": false,
  "trial": false,
  "days_to_end_trial": 0,
  "features": [
    {
      "name": "api_access",
      "days": -1
    },
    {
      "name": "control",
      "days": -1
    },
    {
      "name": "memories",
      "days": -1
    },
    {
      "name": "billing",
      "days": -1
    },
    {
      "name": "project_required_fields",
      "days": -1
    },
    {
      "name": "teams",
      "days": -1
    },
    {
      "name": "recurring_budget",
      "days": -1
    },
    {
      "name": "notifications_project_budget",
      "days": -1
    },
    {
      "name": "weekly_user_capacity",
      "days": -1
    },
    {
      "name": "company_view",
      "days": -1
    },
    {
      "name": "anomalies",
      "days": -1
    },
    {
      "name": "log_hours_for_others",
      "days": -1
    },
    {
      "name": "project_budget",
      "days": -1
    },
    {
      "name": "budgets_hourly_rates",
      "days": -1
    },
    {
      "name": "account_branding",
      "days": -1
    },
    {
      "name": "team_lead",
      "days": -1
    },
    {
      "name": "ai_timesheet_creation",
      "days": -1
    },
    {
      "name": "in_app_support",
      "days": -1
    },
    {
      "name": "people_dashboard",
      "days": -1
    },
    {
      "name": "people_notify",
      "days": -1
    },
    {
      "name": "premium_integrations",
      "days": -1
    },
    {
      "name": "individual_capacity",
      "days": -1
    },
    {
      "name": "audits",
      "days": -1
    },
    {
      "name": "project_dashboard",
      "days": -1
    },
    {
      "name": "high_level_reports",
      "days": -1
    },
    {
      "name": "live_reports",
      "days": -1
    },
    {
      "name": "invoices",
      "days": -1
    },
    {
      "name": "planned_entries",
      "days": -1
    },
    {
      "name": "internal_costs",
      "days": -1
    },
    {
      "name": "memory_retention",
      "days": -1
    },
    {
      "name": "custom_project_currencies",
      "days": -1
    },
    {
      "name": "capacity_reports",
      "days": -1
    },
    {
      "name": "day_locking",
      "days": -1
    },
    {
      "name": "user_custom_properties",
      "days": -1
    },
    {
      "name": "tasks",
      "days": -1
    },
    {
      "name": "planning",
      "days": -1
    },
    {
      "name": "batch_log_planned_time",
      "days": -1
    },
    {
      "name": "ai_labels_suggestions",
      "days": -1
    },
    {
      "name": "integration_monday",
      "days": -1
    },
    {
      "name": "hour_states",
      "days": -1
    },
    {
      "name": "tic_integrations",
      "days": -1
    },
    {
      "name": "tic_support",
      "days": -1
    },
    {
      "name": "import_manager",
      "days": -1
    }
  ]
}

Clients

Clients are the companies that you work for. An account can have multiple clients.

Create a client

This API lets you create a client for an account.

Request

curl "https://api.timelyapp.com/1.1/36/clients" -d '{"name":null,"client":{"name":"Uniq name","active":true,"color":"00796b","external_id":null}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 5o_SlUlWX29GGqc3KAKVO6absINJc3LhxrP7TGEiN4U" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/clients

POST /1.1/36/clients
Accept: application/json
Content-Type: application/json
Authorization: Bearer 5o_SlUlWX29GGqc3KAKVO6absINJc3LhxrP7TGEiN4U

Parameters

{"name":null,"client":{"name":"Uniq name","active":true,"color":"00796b","external_id":null}}
Name Description
name required Specifies the client name
active Example values: "true" or "false". Using "false" changes the client state to "archived"
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)
color Specifies the client color. Example values: 1976d2, 00796b, 2e7d32, d4e157, ffeb3b, ffb74d, ff8a65, e57373, b72367, 7e57c2 (when omitted, a random color will be used)

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 27,
  "name": "Uniq name",
  "color": "00796b",
  "active": true,
  "external_id": null,
  "updated_at": "2025-03-13T08:45:30+01:00"
}

List all clients

NOTE: By default, client list will return first 10000 clients in alphabetical order. You can also use optional parameters like “limit”, “offset”, “show” and “order” to change the results.

Request

curl -g "https://api.timelyapp.com/1.1/37/clients" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer lHeSEzMHUtSOd9bPGBz_5kw5Mbmdh5ow6jq1xVIZ1ww" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/clients

GET /1.1/37/clients
Accept: application/json
Content-Type: application/json
Authorization: Bearer lHeSEzMHUtSOd9bPGBz_5kw5Mbmdh5ow6jq1xVIZ1ww

Parameters

Name Description
account_id Account ID for the clients you want to retrieve
limit Retrieve number of clients
offset Retrieve clients from offset
order "asc (default)" and "desc"
show Specifies which records to retrieve. The default shows a current account’s active clients (show=active). Example: "show=all" or "show=active" or "show=archived"

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 28,
    "name": "Reprehenderit ab voluptatibus quis.",
    "color": "b72367",
    "active": true,
    "external_id": null,
    "updated_at": "2025-03-13T08:45:30+01:00",
    "external_references": []
  }
]

Show client

Request

curl -g "https://api.timelyapp.com/1.1/39/clients/30" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer _W1X7TbQwfkWwxRGM7rt-GAzz4-Nh-TOGK15X2wqNu0" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/clients/:id

GET /1.1/39/clients/30
Accept: application/json
Content-Type: application/json
Authorization: Bearer _W1X7TbQwfkWwxRGM7rt-GAzz4-Nh-TOGK15X2wqNu0

Parameters

Name Description
account_id Account ID for the client you want to retrieve
id Client ID to retrieve

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 30,
  "name": "Ratione ipsa in itaque.",
  "color": "1976d2",
  "active": true,
  "external_id": null,
  "updated_at": "2025-03-13T08:45:31+01:00",
  "external_references": []
}

Update a client

Update client details just by using a client’s ID.

Request

curl "https://api.timelyapp.com/1.1/41/clients/32" -d '{"name":null,"client":{"name":"Updated name","active":true}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer m_dOLymHjSB9p0pZ67bpD6QoBoSjPOqIB6vGo-8G7TM" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/clients/:id

PUT /1.1/41/clients/32
Accept: application/json
Content-Type: application/json
Authorization: Bearer m_dOLymHjSB9p0pZ67bpD6QoBoSjPOqIB6vGo-8G7TM

Parameters

{"name":null,"client":{"name":"Updated name","active":true}}
Name Description
id required Client ID
name required Specifies the client name
active Example values: “true” or “false”. Using “false” changes the client state to “archived”
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)
color Specifies the client color. Example values: 1976d2, 00796b, 2e7d32, d4e157, ffeb3b, ffb74d, ff8a65, e57373, b72367, 7e57c2 (when omitted, the current client color will be used)

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 32,
  "name": "Updated name",
  "color": "b72367",
  "active": true,
  "external_id": null,
  "updated_at": "2025-03-13T08:45:31+01:00"
}

Day locking (Locked Time)

Locked Time helps prevent accidental changes or unauthorized edits, making your time records more trustworthy and dependable. This feature offers you a peace of mind by allowing control over which days, weeks, or months to lock or unlock.

Create a Day locking

This API allow you to lock days for an user.

Request

curl "https://api.timelyapp.com/1.1/42/day_properties" -d '{"day_property":{"user_ids":[93],"dates":["2025-03-13","2025-03-14"],"locked":true}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer JvU83P-V33MuzIyOz6AMMRKkgi51PvOREWtEupsF0O4" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/day_properties

POST /1.1/42/day_properties
Accept: application/json
Content-Type: application/json
Authorization: Bearer JvU83P-V33MuzIyOz6AMMRKkgi51PvOREWtEupsF0O4

Parameters

{"day_property":{"user_ids":[93],"dates":["2025-03-13","2025-03-14"],"locked":true}}
Name Description
user_ids required Specifies the users for which you want lock days. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861"
dates required Specifies the dates to lock, should separated by a comma. Example: dates="2024-08-24, 2024-08-23"
locked Example values: "true" or "false". Using "false" unlocks the days"

Response

Content-Type: application/json; charset=utf-8
201 Created

[
  {
    "id": 1,
    "user_id": 93,
    "account_id": 42,
    "date": "2025-03-13",
    "locked": true,
    "updated_at": 1741851932,
    "created_at": 1741851932
  },
  {
    "id": 2,
    "user_id": 93,
    "account_id": 42,
    "date": "2025-03-14",
    "locked": true,
    "updated_at": 1741851932,
    "created_at": 1741851932
  }
]

List all locked dates

Note: 1. If “since” and “until” parameters are not passed, the period will default to the current week.

2. If the “user_ids” parameters is not passed, the default will be current user's manageable users.

Request

curl -g "https://api.timelyapp.com/1.1/43/day_properties" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 2kjJa3rb70Qk30uhD-Eaqzjixj5tVSgMh1VrKV2PfPI" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/day_properties

GET /1.1/43/day_properties
Accept: application/json
Content-Type: application/json
Authorization: Bearer 2kjJa3rb70Qk30uhD-Eaqzjixj5tVSgMh1VrKV2PfPI

Parameters

Name Description
account_id The account ID containing the locked dates you want to retrieve
since Specifies the start date for returned results. Example: since=2014-08-18
until Specifies the end date for returned results. Example: upto=2014-08-24
dates Specifies the dates for returned results, should separated by a comma. Example: dates="2024-08-24, 2024-08-23"
user_ids Specifies the users for which you want results. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861"

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 3,
    "user_id": 95,
    "account_id": 43,
    "date": "2025-03-13",
    "locked": true,
    "updated_at": 1741851932,
    "created_at": 1741851932
  },
  {
    "id": 4,
    "user_id": 95,
    "account_id": 43,
    "date": "2025-03-14",
    "locked": true,
    "updated_at": 1741851932,
    "created_at": 1741851932
  }
]

Update Day locking

Update locked time by user_ids OR dates.

Request

curl "https://api.timelyapp.com/1.1/44/day_properties" -d '{"day_property":{"user_ids":[97],"dates":["2025-03-13","2025-03-14"],"locked":false}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer DITL0uXcVHNVCz_DxYPmYbO__YwufSw9hPbs0ao2aBk" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/day_properties

PUT /1.1/44/day_properties
Accept: application/json
Content-Type: application/json
Authorization: Bearer DITL0uXcVHNVCz_DxYPmYbO__YwufSw9hPbs0ao2aBk

Parameters

{"day_property":{"user_ids":[97],"dates":["2025-03-13","2025-03-14"],"locked":false}}
Name Description
user_ids required Specifies the users for which you want lock days. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861"
dates required Specifies the dates to lock, should separated by a comma. Example: dates="2024-08-24, 2024-08-23"
locked Example values: "true" or "false". Using "false" unlocks the days"

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 5,
    "user_id": 97,
    "account_id": 44,
    "date": "2025-03-13",
    "locked": false,
    "updated_at": 1741851932,
    "created_at": 1741851932
  },
  {
    "id": 6,
    "user_id": 97,
    "account_id": 44,
    "date": "2025-03-14",
    "locked": false,
    "updated_at": 1741851932,
    "created_at": 1741851932
  }
]

Events

Events are all the entries a user makes. Users can add, delete and edit all entries. Some user’s actions are restricted based on their access level in Timely.

Create an event

When a user creates an event on their own timesheet.

Note: By default, the event is created for a user’s first active project, or the project they last logged time to.

Request

curl "https://api.timelyapp.com/1.1/63/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-03-13T07:45:34.894Z","to":"2025-03-13T11:15:34.894Z","day":"2025-03-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":41}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer D5GkEl8KqjB80WvtTsRD2duoakYfjP51df6O1IiBf9U" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/events

POST /1.1/63/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer D5GkEl8KqjB80WvtTsRD2duoakYfjP51df6O1IiBf9U

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-03-13T07:45:34.894Z","to":"2025-03-13T11:15:34.894Z","day":"2025-03-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":41}}
Name Description
user_id The numerical ID for the user who the event is created for. Note: the default value is the user_id connected to the API token. Example value: 123
day required Event day
hours required Event hours
minutes required Event minutes
estimated_minutes Specifies estimated minutes for an event. Example values: 0-60
estimated_hours Specifies estimated hours for an event. Example values: 0-12
note Specifies notes for an event
from Specifies the “from” time in a timestamp. Example values: from: "2017-05-26T10:00:00+05:30"
to Specifies the “to” time in a timestamp. Example values: to: "2017-05-26T12:00:00+05:30"
label_ids Specifies label IDs for an event. Example values: label_ids:[2,3,4]
project_id Specifies the project ID for an event
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)

Response

Content-Type: application/json; charset=utf-8
201 Created

{
  "id": 64,
  "uid": "ea5d2f1c4608232e07d3aa3d998e5135",
  "user": {
    "id": 135,
    "email": "marijakerllspb@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/8733538d115e8d440417058fcd1c62b4?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/8733538d115e8d440417058fcd1c62b4?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/8733538d115e8d440417058fcd1c62b4?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/8733538d115e8d440417058fcd1c62b4?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/8733538d115e8d440417058fcd1c62b4?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:34+01:00"
  },
  "project": {
    "id": 41,
    "active": true,
    "account_id": 63,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851934,
    "updated_at": 1741851934,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 42,
      "name": "Quam ipsam culpa dolorem.",
      "color": "d4e157",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:34+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 3,
    "minutes": 30,
    "seconds": 0,
    "formatted": "03:30",
    "total_hours": 3.5,
    "total_seconds": 12600,
    "total_minutes": 210
  },
  "estimated_duration": {
    "hours": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 35000,
    "formatted": "$350.00",
    "amount": 350.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851934,
  "created_at": 1741851934,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:34+01:00",
  "from": "2025-03-13T08:45:34+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": 135,
  "updater_id": 135,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [],
  "state": null,
  "external_links": []
}

Create an event for a project

Request

curl "https://api.timelyapp.com/1.1/62/projects/40/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-03-13T07:45:34.632Z","to":"2025-03-13T11:15:34.632Z","day":"2025-03-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":40}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer kO5J0hGzYtlgnu85CdV9jorlZN3x3QGg2kk5OlfTxLM" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/projects/:project_id/events

POST /1.1/62/projects/40/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer kO5J0hGzYtlgnu85CdV9jorlZN3x3QGg2kk5OlfTxLM

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-03-13T07:45:34.632Z","to":"2025-03-13T11:15:34.632Z","day":"2025-03-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":40}}
Name Description
user_id The numerical ID for the user who the event is created for. Note: the default value is the user_id connected to the API token. Example value: 123
day required Event day
hours required Event hours
minutes required Event minutes
project_id required The numerical ID of the desired project. Example values: 123

Response

Content-Type: application/json; charset=utf-8
201 Created

{
  "id": 63,
  "uid": "03afdbd66e7929b125f8597834fa83a4",
  "user": {
    "id": 133,
    "email": "marijaouzbrhhi@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/3a37692955b9ae6a8eb651ac11737e4a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/3a37692955b9ae6a8eb651ac11737e4a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/3a37692955b9ae6a8eb651ac11737e4a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/3a37692955b9ae6a8eb651ac11737e4a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/3a37692955b9ae6a8eb651ac11737e4a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:34+01:00"
  },
  "project": {
    "id": 40,
    "active": true,
    "account_id": 62,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851934,
    "updated_at": 1741851934,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 41,
      "name": "Doloribus sint commodi praesentium.",
      "color": "ff8a65",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:34+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 3,
    "minutes": 30,
    "seconds": 0,
    "formatted": "03:30",
    "total_hours": 3.5,
    "total_seconds": 12600,
    "total_minutes": 210
  },
  "estimated_duration": {
    "hours": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 35000,
    "formatted": "$350.00",
    "amount": 350.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851934,
  "created_at": 1741851934,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:34+01:00",
  "from": "2025-03-13T08:45:34+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": 133,
  "updater_id": 133,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [],
  "state": null,
  "external_links": []
}

Create an event for another user

Note: Normal users can add hours for any user. If a project_id is not provided, the event is created against a user’s first active project, or the project they logged an event to in the last hour.

Request

curl "https://api.timelyapp.com/1.1/61/users/131/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-03-13T07:45:34.362Z","to":"2025-03-13T11:15:34.362Z","day":"2025-03-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":131}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer K33DKYawH5ZdBi_vb5ofC7kGGxLdvqyIQ7SEdB0En5w" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/users/:user_id/events

POST /1.1/61/users/131/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer K33DKYawH5ZdBi_vb5ofC7kGGxLdvqyIQ7SEdB0En5w

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-03-13T07:45:34.362Z","to":"2025-03-13T11:15:34.362Z","day":"2025-03-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":131}}
Name Description
user_id required The numerical ID for the user who the event is created for. Note: the default value is the user_id connected to the API token. Example value: 123
day required Event day
hours required Event hours
minutes required Event minutes

Response

Content-Type: application/json; charset=utf-8
201 Created

{
  "id": 62,
  "uid": "44f683a84163b3523afe57c2e008bc8c",
  "user": {
    "id": 131,
    "email": "marijachxsdpot@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/490c113f92538e02d866e06d9a5fb401?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/490c113f92538e02d866e06d9a5fb401?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/490c113f92538e02d866e06d9a5fb401?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/490c113f92538e02d866e06d9a5fb401?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/490c113f92538e02d866e06d9a5fb401?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:34+01:00"
  },
  "project": {
    "id": 39,
    "active": true,
    "account_id": 61,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851934,
    "updated_at": 1741851934,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 40,
      "name": "Dolores et beatae porro.",
      "color": "d4e157",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:34+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 3,
    "minutes": 30,
    "seconds": 0,
    "formatted": "03:30",
    "total_hours": 3.5,
    "total_seconds": 12600,
    "total_minutes": 210
  },
  "estimated_duration": {
    "hours": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 35000,
    "formatted": "$350.00",
    "amount": 350.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851934,
  "created_at": 1741851934,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:34+01:00",
  "from": "2025-03-13T08:45:34+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": 131,
  "updater_id": 131,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [],
  "state": null,
  "external_links": []
}

Create bulk events

Note: Use the same list of sub-parameters inside your "create" parameter as specified on Create an event. You can create up to 100 events at a time.

Request

curl "https://api.timelyapp.com/1.1/60/bulk/events" -d '{"create":[{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-03-13T07:45:34.109Z","to":"2025-03-13T11:15:34.109Z","day":"2025-03-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":129,"account_id":60,"project_id":38}]}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer PZZTHhCDhLr1AUhqNItmxhHO45v4b1LnyH3Vy5eE2DI" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/bulk/events

POST /1.1/60/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer PZZTHhCDhLr1AUhqNItmxhHO45v4b1LnyH3Vy5eE2DI

Parameters

{"create":[{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-03-13T07:45:34.109Z","to":"2025-03-13T11:15:34.109Z","day":"2025-03-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":129,"account_id":60,"project_id":38}]}
Name Description
create Specifies the parameters for creating a group of events. Example: [{ "hours": 3, "minutes": 30, "seconds": 0, "estimated_hours": 4, "estimated_minutes": 0, "from": "2021-03-04T11:33:36.570+01:00", "to": "2021-03-04T15:03:36.570+01:00", "day": "2021-03-04", "note": "Describe what you worked on here!", "hour_rate": 100, "timer_state": 0, "billed": true, "user_id": 1616, "account_id": 651, "project_id": 620}]

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "deleted_ids": [],
  "created_ids": [
    61
  ],
  "updated_ids": [],
  "errors": {
    "create": [],
    "update": [],
    "delete": []
  },
  "job": null
}

Delete an event

Note: Normal users can delete events logged to other projects by other users on an account. Limited users can only delete their own events.

Request

curl "https://api.timelyapp.com/1.1/65/events/66" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ijOnxBxqvXRkXDnLWSBfJ9U1s1qx4MjIPERcYyAgdy0" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/events/:id

DELETE /1.1/65/events/66
Accept: application/json
Content-Type: application/json
Authorization: Bearer ijOnxBxqvXRkXDnLWSBfJ9U1s1qx4MjIPERcYyAgdy0

Parameters

Name Description
account_id The account ID containing the hour you want to delete
id required The ID for the hour you want to delete

Response

Content-Type: application/json; charset=utf-8
200 OK

{}

Delete bulk events

Note: You can delete up to 100 events at a time.

Request

curl "https://api.timelyapp.com/1.1/64/bulk/events" -d '{"delete":[65]}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer wQLf6XuoeUi63q0bOiIbUF114g7QL97akTq2Ima7Lio" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/bulk/events

POST /1.1/64/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer wQLf6XuoeUi63q0bOiIbUF114g7QL97akTq2Ima7Lio

Parameters

{"delete":[65]}
Name Description
delete Specifies the parameters for deleting a group of events. Example: [ 320, 333 ]

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "deleted_ids": [
    65
  ],
  "created_ids": [],
  "updated_ids": [],
  "errors": {
    "create": [],
    "update": [],
    "delete": []
  },
  "job": null
}

List all events

Get all events linked to active projects on a user’s account.

Note: By default, the API retrieves events from the current date (date of access). To specify a different time range, you need to provide both the “since” and “upto” parameters.

Request

curl -g "https://api.timelyapp.com/1.1/70/events" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer EN9wn-7B16bJ--vhfWCYoJLgumjhrc2zH7FaLmUkjPg" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/events

GET /1.1/70/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer EN9wn-7B16bJ--vhfWCYoJLgumjhrc2zH7FaLmUkjPg

Parameters

Name Description
account_id The account ID containing the hours you want to retrieve.
day Specifies the date for returned events. (Default "current date") Example: day=2014-08-24
since Specifies the start date for returned results. Example: since=2014-08-18
upto Specifies the end date for returned results. Example: upto=2014-08-24
filter Specifies which events to retrieve - logged, all (Default logged)
sort Field to sort events by - updated_at, id, day (Default updated_at)
order Order to retrieve records - desc, asc (Default desc)
per_page Records per page (Default 100)
page Page number (Default 1)

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 71,
    "uid": "e2c420d928d4bf8ce0ff2ec19b371514",
    "user": {
      "id": 149,
      "email": "marijamdtofpuk@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/c61ce9ab01f4531b9affb9484f07c2f9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/c61ce9ab01f4531b9affb9484f07c2f9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/c61ce9ab01f4531b9affb9484f07c2f9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/c61ce9ab01f4531b9affb9484f07c2f9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/c61ce9ab01f4531b9affb9484f07c2f9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2025-03-13T08:45:36+01:00"
    },
    "project": {
      "id": 48,
      "active": true,
      "account_id": 70,
      "name": "Timely",
      "description": "Project Description",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "created_at": 1741851936,
      "updated_at": 1741851936,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 49,
        "name": "Sapiente magni et ut.",
        "color": "d4e157",
        "active": true,
        "external_id": null,
        "updated_at": "2025-03-13T08:45:36+01:00"
      },
      "required_notes": false,
      "required_labels": false,
      "budget_expired_on": null,
      "has_recurrence": false,
      "enable_labels": "all",
      "default_labels": false,
      "currency": {
        "id": "usd",
        "name": "United States Dollar",
        "iso_code": "USD",
        "symbol": "$",
        "symbol_first": true
      },
      "team_ids": [],
      "budget": 0,
      "budget_type": "",
      "budget_calculation": "completed",
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "budget_progress": 0.0,
      "budget_percent": 0.0,
      "invoice_by_budget": false,
      "labels": [],
      "label_ids": [],
      "required_label_ids": [],
      "default_label_ids": [],
      "created_from": "Web"
    },
    "duration": {
      "hours": 3,
      "minutes": 30,
      "seconds": 0,
      "formatted": "03:30",
      "total_hours": 3.5,
      "total_seconds": 12600,
      "total_minutes": 210
    },
    "estimated_duration": {
      "hours": 4,
      "minutes": 0,
      "seconds": 0,
      "formatted": "04:00",
      "total_hours": 4.0,
      "total_seconds": 14400,
      "total_minutes": 240
    },
    "cost": {
      "fractional": 35000,
      "formatted": "$350.00",
      "amount": 350.0,
      "currency_code": "usd"
    },
    "estimated_cost": {
      "fractional": 40000,
      "formatted": "$400.00",
      "amount": 400.0,
      "currency_code": "usd"
    },
    "day": "2025-03-13",
    "note": "Notes for testing with some random #hash in it.",
    "sequence": 1,
    "estimated": false,
    "timer_state": "default",
    "timer_started_on": 0,
    "timer_stopped_on": 0,
    "label_ids": [],
    "user_ids": [],
    "updated_at": 1741851936,
    "created_at": 1741851936,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "billable": true,
    "to": "2025-03-13T12:15:36+01:00",
    "from": "2025-03-13T08:45:36+01:00",
    "deleted": false,
    "hour_rate": 100.0,
    "hour_rate_in_cents": 10000,
    "creator_id": null,
    "updater_id": null,
    "external_id": null,
    "entry_ids": [],
    "suggestion_id": null,
    "draft": false,
    "manage": true,
    "forecast_id": null,
    "billed_at": null,
    "external_link_ids": [],
    "internal_cost": {},
    "estimated_internal_cost": {},
    "internal_cost_rate": 0,
    "profit": 0,
    "profitability": 0,
    "locked_reason": null,
    "locked": false,
    "invoice_id": null,
    "timestamps": [],
    "state": null,
    "external_links": []
  }
]

List all events for a project

Note: By default, the API retrieves events from the current date (date of access). To specify a different time range, you need to provide both the “since” and “upto” parameters.

Request

curl -g "https://api.timelyapp.com/1.1/73/projects/51/events" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer gqT2pP2qrA70bllh-vz8lj0xG6jIUWkvqcPe5EIuVG4" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/projects/:project_id/events

GET /1.1/73/projects/51/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer gqT2pP2qrA70bllh-vz8lj0xG6jIUWkvqcPe5EIuVG4

Parameters

Name Description
account_id The account ID containing the hours you want to retrieve
project_id The project ID for the hours you want to retrieve
day Specifies the date for returned events. (Default "current date") Example: day=2014-08-24
since Specifies the start date for returned results. Example: since=2014-08-18
upto Specifies the end date for returned results. Example: upto=2014-08-24
sort Field to sort events by - updated_at, id, day (Default updated_at)
order Order to retrieve records - desc, asc (Default desc)
per_page Records per page (Default 100)
page Page number (Default 1)

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 74,
    "uid": "ad61ab143223efbc24c7d2583be69251",
    "user": {
      "id": 155,
      "email": "marijagthmltpv@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/d27caadfe60a553abac9275dca821abb?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/d27caadfe60a553abac9275dca821abb?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/d27caadfe60a553abac9275dca821abb?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/d27caadfe60a553abac9275dca821abb?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/d27caadfe60a553abac9275dca821abb?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2025-03-13T08:45:37+01:00"
    },
    "project": {
      "id": 51,
      "active": true,
      "account_id": 73,
      "name": "Timely",
      "description": "Project Description",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "created_at": 1741851937,
      "updated_at": 1741851937,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 52,
        "name": "Nesciunt atque dolore id.",
        "color": "d4e157",
        "active": true,
        "external_id": null,
        "updated_at": "2025-03-13T08:45:37+01:00"
      },
      "required_notes": false,
      "required_labels": false,
      "budget_expired_on": null,
      "has_recurrence": false,
      "enable_labels": "all",
      "default_labels": false,
      "currency": {
        "id": "usd",
        "name": "United States Dollar",
        "iso_code": "USD",
        "symbol": "$",
        "symbol_first": true
      },
      "team_ids": [],
      "budget": 0,
      "budget_type": "",
      "budget_calculation": "completed",
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "budget_progress": 0.0,
      "budget_percent": 0.0,
      "invoice_by_budget": false,
      "labels": [],
      "label_ids": [],
      "required_label_ids": [],
      "default_label_ids": [],
      "created_from": "Web"
    },
    "duration": {
      "hours": 3,
      "minutes": 30,
      "seconds": 0,
      "formatted": "03:30",
      "total_hours": 3.5,
      "total_seconds": 12600,
      "total_minutes": 210
    },
    "estimated_duration": {
      "hours": 4,
      "minutes": 0,
      "seconds": 0,
      "formatted": "04:00",
      "total_hours": 4.0,
      "total_seconds": 14400,
      "total_minutes": 240
    },
    "cost": {
      "fractional": 35000,
      "formatted": "$350.00",
      "amount": 350.0,
      "currency_code": "usd"
    },
    "estimated_cost": {
      "fractional": 40000,
      "formatted": "$400.00",
      "amount": 400.0,
      "currency_code": "usd"
    },
    "day": "2025-03-13",
    "note": "Notes for testing with some random #hash in it.",
    "sequence": 1,
    "estimated": false,
    "timer_state": "default",
    "timer_started_on": 0,
    "timer_stopped_on": 0,
    "label_ids": [],
    "user_ids": [],
    "updated_at": 1741851937,
    "created_at": 1741851937,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "billable": true,
    "to": "2025-03-13T12:15:37+01:00",
    "from": "2025-03-13T08:45:37+01:00",
    "deleted": false,
    "hour_rate": 100.0,
    "hour_rate_in_cents": 10000,
    "creator_id": null,
    "updater_id": null,
    "external_id": null,
    "entry_ids": [],
    "suggestion_id": null,
    "draft": false,
    "manage": true,
    "forecast_id": null,
    "billed_at": null,
    "external_link_ids": [],
    "internal_cost": {},
    "estimated_internal_cost": {},
    "internal_cost_rate": 0,
    "profit": 0,
    "profitability": 0,
    "locked_reason": null,
    "locked": false,
    "invoice_id": null,
    "timestamps": [],
    "state": null,
    "external_links": []
  }
]

List all events for a user

Note: By default, the API retrieves events from the current date (date of access). To specify a different time range, you need to provide both the “since” and “upto” parameters.

Request

curl -g "https://api.timelyapp.com/1.1/72/users/153/events" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer NZD8tSWTh6GcbJ3nyQD76v1aNTJzZWjFKrm3h7NkAeA" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/:user_id/events

GET /1.1/72/users/153/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer NZD8tSWTh6GcbJ3nyQD76v1aNTJzZWjFKrm3h7NkAeA

Parameters

Name Description
account_id The account ID containing the hours you want to retrieve
user_id The user ID for the hours you want to retrieve
day Specifies the date for returned events. (Default "current date") Example: day=2014-08-24
since Specifies the start date for returned results. Example: since=2014-08-18
upto Specifies the end date for returned results. Example: upto=2014-08-24
sort Field to sort events by - updated_at, id, day (Default updated_at)
order Order to retrieve records - desc, asc (Default desc)
per_page Records per page (Default 100)
page Page number (Default 1)

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 73,
    "uid": "d2ddea18f00665ce8623e36bd4e3c7c5",
    "user": {
      "id": 153,
      "email": "marijajckcfjxg@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/d60d734fb39086d49af2869caf94df1e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/d60d734fb39086d49af2869caf94df1e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/d60d734fb39086d49af2869caf94df1e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/d60d734fb39086d49af2869caf94df1e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/d60d734fb39086d49af2869caf94df1e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2025-03-13T08:45:36+01:00"
    },
    "project": {
      "id": 50,
      "active": true,
      "account_id": 72,
      "name": "Timely",
      "description": "Project Description",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "created_at": 1741851937,
      "updated_at": 1741851937,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 51,
        "name": "Omnis molestiae ut natus.",
        "color": "e57373",
        "active": true,
        "external_id": null,
        "updated_at": "2025-03-13T08:45:37+01:00"
      },
      "required_notes": false,
      "required_labels": false,
      "budget_expired_on": null,
      "has_recurrence": false,
      "enable_labels": "all",
      "default_labels": false,
      "currency": {
        "id": "usd",
        "name": "United States Dollar",
        "iso_code": "USD",
        "symbol": "$",
        "symbol_first": true
      },
      "team_ids": [],
      "budget": 0,
      "budget_type": "",
      "budget_calculation": "completed",
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "budget_progress": 0.0,
      "budget_percent": 0.0,
      "invoice_by_budget": false,
      "labels": [],
      "label_ids": [],
      "required_label_ids": [],
      "default_label_ids": [],
      "created_from": "Web"
    },
    "duration": {
      "hours": 3,
      "minutes": 30,
      "seconds": 0,
      "formatted": "03:30",
      "total_hours": 3.5,
      "total_seconds": 12600,
      "total_minutes": 210
    },
    "estimated_duration": {
      "hours": 4,
      "minutes": 0,
      "seconds": 0,
      "formatted": "04:00",
      "total_hours": 4.0,
      "total_seconds": 14400,
      "total_minutes": 240
    },
    "cost": {
      "fractional": 35000,
      "formatted": "$350.00",
      "amount": 350.0,
      "currency_code": "usd"
    },
    "estimated_cost": {
      "fractional": 40000,
      "formatted": "$400.00",
      "amount": 400.0,
      "currency_code": "usd"
    },
    "day": "2025-03-13",
    "note": "Notes for testing with some random #hash in it.",
    "sequence": 1,
    "estimated": false,
    "timer_state": "default",
    "timer_started_on": 0,
    "timer_stopped_on": 0,
    "label_ids": [],
    "user_ids": [],
    "updated_at": 1741851937,
    "created_at": 1741851937,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "billable": true,
    "to": "2025-03-13T12:15:37+01:00",
    "from": "2025-03-13T08:45:37+01:00",
    "deleted": false,
    "hour_rate": 100.0,
    "hour_rate_in_cents": 10000,
    "creator_id": null,
    "updater_id": null,
    "external_id": null,
    "entry_ids": [],
    "suggestion_id": null,
    "draft": false,
    "manage": true,
    "forecast_id": null,
    "billed_at": null,
    "external_link_ids": [],
    "internal_cost": {},
    "estimated_internal_cost": {},
    "internal_cost_rate": 0,
    "profit": 0,
    "profitability": 0,
    "locked_reason": null,
    "locked": false,
    "invoice_id": null,
    "timestamps": [],
    "state": null,
    "external_links": []
  }
]

Logged in user updating details and user of an event

Request

curl "https://api.timelyapp.com/1.1/81/users/171/events/82" -d '{"event":{"note":"Updated details and project","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer vYB5NVr6m1MMIYlgW8d7SWKWfJwU6FEiVzemZPbjtqk" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/users/:user_id/events/:id

PUT /1.1/81/users/171/events/82
Accept: application/json
Content-Type: application/json
Authorization: Bearer vYB5NVr6m1MMIYlgW8d7SWKWfJwU6FEiVzemZPbjtqk

Parameters

{"event":{"note":"Updated details and project","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}
Name Description
id required Event ID
day required Event day
hours required Event hours
minutes required Event minutes
estimated_minutes Specifies estimated minutes for an event. Example values: 0-60
estimated_hours Specifies estimated hours for an event. Example values: 0-12
note Specifies notes for an event
from Specifies the “from” time in a timestamp. Example values: from: "2017-05-26T10:00:00+05:30"
to Specifies the “to” time in a timestamp. Example values: to: "2017-05-26T12:00:00+05:30"
label_ids Specifies label IDs for an event. Example values: label_ids:[2,3,4]
project_id Specifies the project ID for an event
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 82,
  "uid": "9778d5d219c5080b9a6a17bef029331c",
  "user": {
    "id": 171,
    "email": "marijajqmellgp@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/4b2ba99a5e7b4fcc1b27d8ce3406b113?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/4b2ba99a5e7b4fcc1b27d8ce3406b113?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/4b2ba99a5e7b4fcc1b27d8ce3406b113?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/4b2ba99a5e7b4fcc1b27d8ce3406b113?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/4b2ba99a5e7b4fcc1b27d8ce3406b113?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:39+01:00"
  },
  "project": {
    "id": 59,
    "active": true,
    "account_id": 81,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851939,
    "updated_at": 1741851939,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 60,
      "name": "Repellat est iure vitae.",
      "color": "e57373",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:39+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "estimated_duration": {
    "hours": 2,
    "minutes": 0,
    "seconds": 0,
    "formatted": "02:00",
    "total_hours": 2.0,
    "total_seconds": 7200,
    "total_minutes": 120
  },
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Updated details and project",
  "sequence": 1,
  "estimated": true,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851939,
  "created_at": 1741851939,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:39+01:00",
  "from": "2025-03-13T08:45:39+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 171,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [],
  "state": null,
  "external_links": []
}

Loggedin user updating details and project of their event

Request

curl "https://api.timelyapp.com/1.1/80/projects/58/events/81" -d '{"event":{"note":"Updated details and project","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer GsjueSH2c8CuPE2gTwHFwCwe0m3OFtypTv6zOSYFRHQ" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/projects/:project_id/events/:id

PUT /1.1/80/projects/58/events/81
Accept: application/json
Content-Type: application/json
Authorization: Bearer GsjueSH2c8CuPE2gTwHFwCwe0m3OFtypTv6zOSYFRHQ

Parameters

{"event":{"note":"Updated details and project","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}
Name Description
id required Event ID
project_id required Project ID
day required Event day
hours required Event hours
minutes required Event minutes
estimated_minutes Specifies estimated minutes for an event. Example values: 0-60
estimated_hours Specifies estimated hours for an event. Example values: 0-12
note Specifies notes for an event
from Specifies the “from” time in a timestamp. Example values: from: "2017-05-26T10:00:00+05:30"
to Specifies the “to” time in a timestamp. Example values: to: "2017-05-26T12:00:00+05:30"
label_ids Specifies label IDs for an event. Example values: label_ids:[2,3,4]
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 81,
  "uid": "43ec517d68b6edd3015b3edc9a11367b",
  "user": {
    "id": 169,
    "email": "marijaqppiszqr@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/da0140ef08e0c92b8a8b5bab9c1d2eee?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/da0140ef08e0c92b8a8b5bab9c1d2eee?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/da0140ef08e0c92b8a8b5bab9c1d2eee?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/da0140ef08e0c92b8a8b5bab9c1d2eee?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/da0140ef08e0c92b8a8b5bab9c1d2eee?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:38+01:00"
  },
  "project": {
    "id": 58,
    "active": true,
    "account_id": 80,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851939,
    "updated_at": 1741851939,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 59,
      "name": "Voluptas aut dolores quibusdam.",
      "color": "7e57c2",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:39+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "estimated_duration": {
    "hours": 2,
    "minutes": 0,
    "seconds": 0,
    "formatted": "02:00",
    "total_hours": 2.0,
    "total_seconds": 7200,
    "total_minutes": 120
  },
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Updated details and project",
  "sequence": 1,
  "estimated": true,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851939,
  "created_at": 1741851939,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:39+01:00",
  "from": "2025-03-13T08:45:39+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 169,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [],
  "state": null,
  "external_links": []
}

Retrieve an event

Request

curl -g "https://api.timelyapp.com/1.1/68/events/69" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 8-gbBAzY-3aTjbWToOGM9Rwt89Zy_ocYLegfWukspss" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/events/:id

GET /1.1/68/events/69
Accept: application/json
Content-Type: application/json
Authorization: Bearer 8-gbBAzY-3aTjbWToOGM9Rwt89Zy_ocYLegfWukspss

Parameters

Name Description
account_id The account ID containing the hour you want to retrieve
id The ID of the hour you want to retrieve

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 69,
  "uid": "14bfa6bb14875e45bba028a21ed38046",
  "user": {
    "id": 145,
    "email": "marijaajdmsjto@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/bb08a6088dd3d74bce7be8ca010efa39?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/bb08a6088dd3d74bce7be8ca010efa39?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/bb08a6088dd3d74bce7be8ca010efa39?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/bb08a6088dd3d74bce7be8ca010efa39?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/bb08a6088dd3d74bce7be8ca010efa39?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:35+01:00"
  },
  "project": {
    "id": 46,
    "active": true,
    "account_id": 68,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851936,
    "updated_at": 1741851936,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 47,
      "name": "Autem nisi nobis qui.",
      "color": "ffeb3b",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:36+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 3,
    "minutes": 30,
    "seconds": 0,
    "formatted": "03:30",
    "total_hours": 3.5,
    "total_seconds": 12600,
    "total_minutes": 210
  },
  "estimated_duration": {
    "hours": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 35000,
    "formatted": "$350.00",
    "amount": 350.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851936,
  "created_at": 1741851936,
  "created_from": "Web",
  "updated_from": "Web",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:36+01:00",
  "from": "2025-03-13T08:45:36+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": null,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [],
  "state": null,
  "external_links": []
}

Start timer on an event

Request

curl "https://api.timelyapp.com/1.1/74/events/75/start" -d '' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Fl2c2ScD4OQmEzAOseJB78oDlSwmpUXmTc-iutbov-Y" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/events/:id/start

PUT /1.1/74/events/75/start
Accept: application/json
Content-Type: application/json
Authorization: Bearer Fl2c2ScD4OQmEzAOseJB78oDlSwmpUXmTc-iutbov-Y

Parameters

Name Description
id required Event ID

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 75,
  "uid": "d09bf41544a3365a46c9077ebb5e35c3",
  "user": {
    "id": 157,
    "email": "marijacizrzypx@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/ff94d46a880b6557946323afb9c750cd?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/ff94d46a880b6557946323afb9c750cd?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/ff94d46a880b6557946323afb9c750cd?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/ff94d46a880b6557946323afb9c750cd?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/ff94d46a880b6557946323afb9c750cd?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:37+01:00"
  },
  "project": {
    "id": 52,
    "active": true,
    "account_id": 74,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851937,
    "updated_at": 1741851937,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 53,
      "name": "Fugit nulla cumque magni.",
      "color": "00796b",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:37+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 3,
    "minutes": 30,
    "seconds": 0,
    "formatted": "03:30",
    "total_hours": 3.5,
    "total_seconds": 12600,
    "total_minutes": 210
  },
  "estimated_duration": {
    "hours": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 35000,
    "formatted": "$350.00",
    "amount": 350.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "start",
  "timer_started_on": 1741851937,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851937,
  "created_at": 1741851937,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:37+01:00",
  "from": "2025-03-13T08:45:37+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 157,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [
    {
      "id": 1,
      "hour_id": 75,
      "from": "2025-03-13T05:15:37+01:00",
      "to": "2025-03-13T08:45:37+01:00",
      "entry_ids": []
    }
  ],
  "state": null,
  "external_links": []
}

Stop timer on an event

Request

curl "https://api.timelyapp.com/1.1/75/events/76/stop" -d '' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer gfKTKeF7DrptJUXy53uAcigsp9HiHxx2V7rKPVXw_jo" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/events/:id/stop

PUT /1.1/75/events/76/stop
Accept: application/json
Content-Type: application/json
Authorization: Bearer gfKTKeF7DrptJUXy53uAcigsp9HiHxx2V7rKPVXw_jo

Parameters

Name Description
id required Event ID

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 76,
  "uid": "fbd7939d674997cdb4692d34de8633c4",
  "user": {
    "id": 159,
    "email": "marijajitxgngd@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/458df0c7d2df8f5ff50e6ef0adb66b51?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/458df0c7d2df8f5ff50e6ef0adb66b51?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/458df0c7d2df8f5ff50e6ef0adb66b51?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/458df0c7d2df8f5ff50e6ef0adb66b51?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/458df0c7d2df8f5ff50e6ef0adb66b51?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:37+01:00"
  },
  "project": {
    "id": 53,
    "active": true,
    "account_id": 75,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851937,
    "updated_at": 1741851937,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 54,
      "name": "Aperiam hic autem perferendis.",
      "color": "ff8a65",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:37+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 4,
    "minutes": 30,
    "seconds": 0,
    "formatted": "04:30",
    "total_hours": 4.5,
    "total_seconds": 16200,
    "total_minutes": 270
  },
  "estimated_duration": {
    "hours": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 45000,
    "formatted": "$450.00",
    "amount": 450.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "stop",
  "timer_started_on": 0,
  "timer_stopped_on": 1741851937,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851937,
  "created_at": 1741851937,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:37+01:00",
  "from": "2025-03-13T08:45:37+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 159,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [],
  "state": null,
  "external_links": []
}

Update an event

Request

curl "https://api.timelyapp.com/1.1/79/events/80" -d '{"event":{"note":"Updated notes","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer hpjJhUBAgnQlVSMxG4rXMnpxA4_jlRows1vaLxT50DY" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/events/:id

PUT /1.1/79/events/80
Accept: application/json
Content-Type: application/json
Authorization: Bearer hpjJhUBAgnQlVSMxG4rXMnpxA4_jlRows1vaLxT50DY

Parameters

{"event":{"note":"Updated notes","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}
Name Description
user_id The numerical ID for the user who the event is updated for. Note: the default value is the user_id connected to the API token. Example value: 123
id required Event ID
day required Event day
hours required Event hours
minutes required Event minutes
project_id Project ID
estimated_minutes Specifies estimated minutes for an event. Example values: 0-60
estimated_hours Specifies estimated hours for an event. Example values: 0-12
note Specifies notes for an event
from Specifies the “from” time in a timestamp. Example values: from: "2017-05-26T10:00:00+05:30"
to Specifies the “to” time in a timestamp. Example values: to: "2017-05-26T12:00:00+05:30"
label_ids Specifies label IDs for an event. Example values: label_ids:[2,3,4]
external_id The external_id can be used to reference external resource ids to Timely resources, should be alphanumeric 512 characters
billed Specifies whether you want an event to be marked as billed. For example: 'billed': false or 'billed': true
billable Specifies whether you want an event to be billable or non-billable. For example: 'billable': false or 'billable': true

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 80,
  "uid": "f033ab37c30201f73f142449d037028d",
  "user": {
    "id": 167,
    "email": "marijacnpwcdsb@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/65047b9c7526d84edd749e3641fa26be?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/65047b9c7526d84edd749e3641fa26be?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/65047b9c7526d84edd749e3641fa26be?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/65047b9c7526d84edd749e3641fa26be?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/65047b9c7526d84edd749e3641fa26be?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:38+01:00"
  },
  "project": {
    "id": 57,
    "active": true,
    "account_id": 79,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851938,
    "updated_at": 1741851938,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 58,
      "name": "Et velit provident nihil.",
      "color": "7e57c2",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:38+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "created_from": "Web"
  },
  "duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "estimated_duration": {
    "hours": 2,
    "minutes": 0,
    "seconds": 0,
    "formatted": "02:00",
    "total_hours": 2.0,
    "total_seconds": 7200,
    "total_minutes": 120
  },
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0,
    "currency_code": "usd"
  },
  "day": "2025-03-13",
  "note": "Updated notes",
  "sequence": 1,
  "estimated": true,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1741851938,
  "created_at": 1741851938,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2025-03-13T12:15:38+01:00",
  "from": "2025-03-13T08:45:38+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 167,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "external_link_ids": [],
  "internal_cost": {},
  "estimated_internal_cost": {},
  "internal_cost_rate": 0,
  "profit": 0,
  "profitability": 0,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": [],
  "state": null,
  "external_links": []
}

Update bulk events

Note: Use the same list of sub-parameters inside your "update" parameter as specified on Update an event. You can update up to 100 events at a time.

Request

curl "https://api.timelyapp.com/1.1/76/bulk/events" -d '{"update":[{"id":77,"note":"updated","billed":true}]}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YaY0XQIBGJNDhRaldikyFv2UXY2XLZrBHbb5awtxplo" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/bulk/events

POST /1.1/76/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer YaY0XQIBGJNDhRaldikyFv2UXY2XLZrBHbb5awtxplo

Parameters

{"update":[{"id":77,"note":"updated","billed":true}]}
Name Description
update Specifies the parameters for updating a group of events. Example: [{ "id": 1055, "note": "updated", "billed": true }]

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "deleted_ids": [],
  "created_ids": [],
  "updated_ids": [
    77
  ],
  "errors": {
    "create": [],
    "update": [],
    "delete": []
  },
  "job": null
}

Forecasts (Tasks)

Forecasts (Tasks) lets you visualize upcoming work for all Timely users in one clean calendar view. You can then quickly assign work or edit plans across your different projects and teams.

Create a forecast

Request

curl "https://api.timelyapp.com/1.1/113/forecasts" -d '{"forecast":{"from":"2022-05-10","to":"2022-05-16","estimated_minutes":150,"users":[{"id":234}],"project_id":74,"title":"Title"}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer aHRC90D_LfH6zSK9v9bV13KTOBNYvj5t89wPwdn-WCY" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/forecasts

POST /1.1/113/forecasts
Accept: application/json
Content-Type: application/json
Authorization: Bearer aHRC90D_LfH6zSK9v9bV13KTOBNYvj5t89wPwdn-WCY

Parameters

{"forecast":{"from":"2022-05-10","to":"2022-05-16","estimated_minutes":150,"users":[{"id":234}],"project_id":74,"title":"Title"}}
Name Description
estimated_minutes Forecast minutes
title Specifies title for a forecast
from Specifies the “from” time in a timestamp. Example values: from: "2022-05-26T10:00:00+05:30"
to Specifies the “to” time in a timestamp. Example values: to: "2022-05-26T12:00:00+05:30"
users Forecast assignees. Example values: [{ id: 1 }, { id: 3 }]
project_id required The numerical ID of the desired project. Example values: 123
label_ids Specifies label IDs for a forecast. Example values: label_ids:[2,3,4]
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)

Response

Content-Type: application/json; charset=utf-8
201 Created

{
  "id": 9,
  "note": "Title",
  "title": "Title",
  "description": "",
  "from": "2022-05-10",
  "to": "2022-05-16",
  "user": {
    "id": 234,
    "email": "marijacevmoetl@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:41+01:00",
    "estimated_minutes": 150,
    "estimated_duration": {
      "hours": 2,
      "minutes": 30,
      "seconds": 0,
      "formatted": "02:30",
      "total_hours": 2.5,
      "total_seconds": 9000,
      "total_minutes": 150
    },
    "weekly_capacity": 40.0,
    "work_days": "MON,TUE,WED,THU,FRI",
    "weekdays": "MO,TU,WE,TH,FR"
  },
  "users": [
    {
      "id": 234,
      "email": "marijacevmoetl@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/36fd05a7642a57100583e144b554b227?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2025-03-13T08:45:41+01:00",
      "estimated_minutes": 0,
      "estimated_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "weekly_capacity": 40.0,
      "work_days": "MON,TUE,WED,THU,FRI",
      "weekdays": "MO,TU,WE,TH,FR"
    }
  ],
  "project": {
    "id": 74,
    "active": true,
    "name": "Timely",
    "color": "67a3bc",
    "client": {
      "id": 83,
      "name": "Quia id autem consequatur.",
      "color": "00796b",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:41+01:00"
    },
    "updated_at": "2025-03-13T08:45:41+01:00"
  },
  "estimated_minutes": 150,
  "updated_at": "2025-03-13T08:45:42+01:00",
  "created_at": "2025-03-13T08:45:42+01:00",
  "label_ids": [],
  "estimated_duration": {
    "hours": 2,
    "minutes": 30,
    "seconds": 0,
    "formatted": "02:30",
    "total_hours": 2.5,
    "total_seconds": 9000,
    "total_minutes": 150
  },
  "planned_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "logged_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "completed": false,
  "completed_at": null,
  "manage": true,
  "external_id": null
}

Delete a forecast

Request

curl "https://api.timelyapp.com/1.1/114/forecasts/10" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer NSg31_fFApY-DXAyWiWGbktxXA1jfgalrUfLM9DIrXk" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/forecasts/:id

DELETE /1.1/114/forecasts/10
Accept: application/json
Content-Type: application/json
Authorization: Bearer NSg31_fFApY-DXAyWiWGbktxXA1jfgalrUfLM9DIrXk

Parameters

Name Description
account_id The account ID containing the forecast you want to delete
id required The ID for the forecast you want to delete

Response

Content-Type: application/json; charset=utf-8
200 OK

{}

List all forecasts

Request

curl -g "https://api.timelyapp.com/1.1/115/forecasts" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 3BMSodUEPZzB407HUUROq_SO8Z5BcaxMjBCrzGZS7go" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/forecasts

GET /1.1/115/forecasts
Accept: application/json
Content-Type: application/json
Authorization: Bearer 3BMSodUEPZzB407HUUROq_SO8Z5BcaxMjBCrzGZS7go

Parameters

Name Description
account_id The account ID containing the forecasts you want to retrieve
since Specifies the start date for returned results. Example: since=2014-08-18
upto Specifies the end date for returned results. Example: upto=2014-08-24
forecast_ids Specifies the forecasts for which you want results. Numerical forecast IDs should separated by a comma, like so: "forecast_ids": "175551,117861"
user_ids Specifies the users for which you want results. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861"
project_ids Specifies the projects for which you want results. Numerical project IDs should be separated by a comma, like so: "project_ids": "1751,1171"
page Page number (Default 1)
per_page Records per page (Default 50)

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 11,
    "note": "title",
    "title": "title",
    "description": null,
    "from": "2025-03-10",
    "to": "2025-03-16",
    "user": {
      "id": 241,
      "email": "quentincqufzjli@timelyapp.com",
      "name": "Quintin Duponde",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/c81a00dd1273662500e08fc6144410b3?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/c81a00dd1273662500e08fc6144410b3?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/c81a00dd1273662500e08fc6144410b3?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/c81a00dd1273662500e08fc6144410b3?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/c81a00dd1273662500e08fc6144410b3?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2025-03-13T08:45:42+01:00",
      "estimated_minutes": 360,
      "estimated_duration": {
        "hours": 6,
        "minutes": 0,
        "seconds": 0,
        "formatted": "06:00",
        "total_hours": 6.0,
        "total_seconds": 21600,
        "total_minutes": 360
      },
      "weekly_capacity": 40.0,
      "work_days": "MON,TUE,WED,THU,FRI",
      "weekdays": "MO,TU,WE,TH,FR"
    },
    "users": [
      {
        "id": 239,
        "email": "marijacessuzfu@timelyapp.com",
        "name": "Marija Petrovic",
        "avatar": {
          "large_retina": "https://www.gravatar.com/avatar/a264804b8125de2cfee968d0d35344c8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
          "large": "https://www.gravatar.com/avatar/a264804b8125de2cfee968d0d35344c8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
          "medium_retina": "https://www.gravatar.com/avatar/a264804b8125de2cfee968d0d35344c8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
          "medium": "https://www.gravatar.com/avatar/a264804b8125de2cfee968d0d35344c8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
          "timeline": "https://www.gravatar.com/avatar/a264804b8125de2cfee968d0d35344c8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
        },
        "updated_at": "2025-03-13T08:45:42+01:00",
        "estimated_minutes": 0,
        "estimated_duration": {
          "hours": 0,
          "minutes": 0,
          "seconds": 0,
          "formatted": "00:00",
          "total_hours": 0.0,
          "total_seconds": 0,
          "total_minutes": 0
        },
        "weekly_capacity": 40.0,
        "work_days": "MON,TUE,WED,THU,FRI",
        "weekdays": "MO,TU,WE,TH,FR"
      }
    ],
    "project": {
      "id": 76,
      "active": true,
      "name": "Timely",
      "color": "67a3bc",
      "client": {
        "id": 85,
        "name": "Ut quae et est.",
        "color": "ffeb3b",
        "active": true,
        "external_id": null,
        "updated_at": "2025-03-13T08:45:42+01:00"
      },
      "updated_at": "2025-03-13T08:45:42+01:00"
    },
    "estimated_minutes": 360,
    "updated_at": "2025-03-13T08:45:42+01:00",
    "created_at": "2025-03-13T08:45:42+01:00",
    "label_ids": [],
    "estimated_duration": {
      "hours": 6,
      "minutes": 0,
      "seconds": 0,
      "formatted": "06:00",
      "total_hours": 6.0,
      "total_seconds": 21600,
      "total_minutes": 360
    },
    "planned_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "logged_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "completed": false,
    "completed_at": null,
    "manage": true,
    "external_id": null
  }
]

Update a forecast

Request

curl "https://api.timelyapp.com/1.1/116/forecasts/12" -d '{"forecast":{"from":"2022-05-10","to":"2022-05-16","estimated_minutes":30,"users":[{"id":242}],"project_id":77,"title":"new title"}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer zFfyneBoP_nY9I9YDRY2EC7jYY1cLfatj97LYEiH2xM" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/forecasts/:id

PUT /1.1/116/forecasts/12
Accept: application/json
Content-Type: application/json
Authorization: Bearer zFfyneBoP_nY9I9YDRY2EC7jYY1cLfatj97LYEiH2xM

Parameters

{"forecast":{"from":"2022-05-10","to":"2022-05-16","estimated_minutes":30,"users":[{"id":242}],"project_id":77,"title":"new title"}}
Name Description
id required Forecast ID
estimated_minutes required Forecast minutes
title Specifies title for a forecast
from Specifies the “from” time in a timestamp. Example values: from: "2022-05-26T10:00:00+05:30"
to Specifies the “to” time in a timestamp. Example values: to: "2022-05-26T12:00:00+05:30"
users Forecast assignees. Example values: [{ id: 1 }, { id: 3 }]
project_id required The numerical ID of the desired project. Example values: 123
label_ids Specifies label IDs for a forecast. Example values: label_ids:[2,3,4]
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 12,
  "note": "new title",
  "title": "new title",
  "description": "",
  "from": "2022-05-10",
  "to": "2022-05-16",
  "user": {
    "id": 242,
    "email": "marijambgkjgyx@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2025-03-13T08:45:42+01:00",
    "estimated_minutes": 30,
    "estimated_duration": {
      "hours": 0,
      "minutes": 30,
      "seconds": 0,
      "formatted": "00:30",
      "total_hours": 0.5,
      "total_seconds": 1800,
      "total_minutes": 30
    },
    "weekly_capacity": 40.0,
    "work_days": "MON,TUE,WED,THU,FRI",
    "weekdays": "MO,TU,WE,TH,FR"
  },
  "users": [
    {
      "id": 242,
      "email": "marijambgkjgyx@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/99dbf1fb13f44938256230e1b2317515?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2025-03-13T08:45:42+01:00",
      "estimated_minutes": 0,
      "estimated_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "weekly_capacity": 40.0,
      "work_days": "MON,TUE,WED,THU,FRI",
      "weekdays": "MO,TU,WE,TH,FR"
    }
  ],
  "project": {
    "id": 77,
    "active": true,
    "name": "Timely",
    "color": "67a3bc",
    "client": {
      "id": 86,
      "name": "Repellat rerum odio sit.",
      "color": "e57373",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:42+01:00"
    },
    "updated_at": "2025-03-13T08:45:42+01:00"
  },
  "estimated_minutes": 30,
  "updated_at": "2025-03-13T08:45:42+01:00",
  "created_at": "2025-03-13T08:45:42+01:00",
  "label_ids": [],
  "estimated_duration": {
    "hours": 0,
    "minutes": 30,
    "seconds": 0,
    "formatted": "00:30",
    "total_hours": 0.5,
    "total_seconds": 1800,
    "total_minutes": 30
  },
  "planned_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "logged_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "completed": false,
  "completed_at": null,
  "manage": true,
  "external_id": null
}

Labels

Labels (AKA Tags) help you classify work, group related tasks and require certain information for events. This API lets you to create, list, update and delete tags created on an account.

Create a label

Request

curl "https://api.timelyapp.com/1.1/154/labels" -d '{"name":null,"label":{"name":"Web Programming","active":true}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer U5bp1zqV9TTWbI-k7tA1zkZ1fDtJWpPTw3_9wZf6bL0" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/labels

POST /1.1/154/labels
Accept: application/json
Content-Type: application/json
Authorization: Bearer U5bp1zqV9TTWbI-k7tA1zkZ1fDtJWpPTw3_9wZf6bL0

Parameters

{"name":null,"label":{"name":"Web Programming","active":true}}
Name Description
name required Specifies the label name
emoji Specifies the emoji url for a label
parent_id Set a parent_id if you want to create a child label
active Example values: "true" or "false". Using "false" changes the label state to "archived"

Response

Content-Type: application/json; charset=utf-8
201 Created

{
  "id": 1,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": "https://emoji.memorycdn.com/tw64/1f3f7-fe0f.png",
  "active": true,
  "created_at": "2025-03-13T08:45:46+01:00",
  "updated_at": "2025-03-13T08:45:46+01:00",
  "children": []
}

Delete a label

Request

curl "https://api.timelyapp.com/1.1/155/labels/2" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer OI7zltv3PAsxqZ3BK7lDtAr4NRv5BvIji2OoI9uFz7c" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/labels/:id

DELETE /1.1/155/labels/2
Accept: application/json
Content-Type: application/json
Authorization: Bearer OI7zltv3PAsxqZ3BK7lDtAr4NRv5BvIji2OoI9uFz7c

Parameters

Name Description
account_id The account ID containing the label you want to delete
id The ID of the label you want to delete

Response

Content-Type: application/json; charset=utf-8
200 OK

{}

List all child labels

Get the children of any tag on a user’s account.

Request

curl -g "https://api.timelyapp.com/1.1/158/labels?parent_id=4" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer gMGJN7PZSRRq5U0Bsw_YQIKQ42sRCjjg5DCBN1OcUaU" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/labels

GET /1.1/158/labels?parent_id=4
Accept: application/json
Content-Type: application/json
Authorization: Bearer gMGJN7PZSRRq5U0Bsw_YQIKQ42sRCjjg5DCBN1OcUaU

Parameters

parent_id: 4
Name Description
account_id The account ID containing the label you want to. retrieve
parent_id The parent ID whose children you want to retrieve

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 4,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": null,
  "active": true,
  "created_at": "2025-03-13T08:45:47+01:00",
  "updated_at": "2025-03-13T08:45:47+01:00",
  "children": []
}

List all labels

Get all the tags present in user’s account.

Request

curl -g "https://api.timelyapp.com/1.1/157/labels" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer IXHTnSgRSNE193oNroiU69ZhlyDvr0-aHQ9BR4cp-Go" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/labels

GET /1.1/157/labels
Accept: application/json
Content-Type: application/json
Authorization: Bearer IXHTnSgRSNE193oNroiU69ZhlyDvr0-aHQ9BR4cp-Go

Parameters

Name Description
account_id The account ID containing the label you want to. retrieve
offset Retrieve labels from offset
limit Retrieve number of labels
filter Specifies which records to retrieve. The default shows a current workspace’s all labels (filter=all). Example: "filter=all" or "filter=active" or "filter=archived"

Response

Content-Type: application/json; charset=utf-8
200 OK

[]

Retrieve a label

Get single tags present in user’s account.

Request

curl -g "https://api.timelyapp.com/1.1/156/labels/3" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer pbkLktBJxPoAbm65JNC19sa39o55m_mz9zru3FbCa0s" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/labels/:id

GET /1.1/156/labels/3
Accept: application/json
Content-Type: application/json
Authorization: Bearer pbkLktBJxPoAbm65JNC19sa39o55m_mz9zru3FbCa0s

Parameters

Name Description
account_id The account ID containing the label you want to. retrieve
id The ID of the label you want to retrieve

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 3,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": null,
  "active": true,
  "created_at": "2025-03-13T08:45:47+01:00",
  "updated_at": "2025-03-13T08:45:47+01:00",
  "children": []
}

Update a label

Request

curl "https://api.timelyapp.com/1.1/159/labels/5" -d '{"name":null,"label":{"name":"updated name"}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer mkoA2owtZ24U8oWf2rKx5aL4I8giOEKOXukb1Ws6D0s" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/labels/:id

PUT /1.1/159/labels/5
Accept: application/json
Content-Type: application/json
Authorization: Bearer mkoA2owtZ24U8oWf2rKx5aL4I8giOEKOXukb1Ws6D0s

Parameters

{"name":null,"label":{"name":"updated name"}}
Name Description
id required Label ID
name required Specifies the label name
emoji Specifies the emoji url for a tag
parent_id Set a parent_id if you want to create a child label
active Example values: "true" or "false". Using "false" changes the label state to "archived"

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 5,
  "name": "updated name",
  "sequence": 1,
  "parent_id": null,
  "emoji": "https://emoji.memorycdn.com/tw64/1f3f7-fe0f.png",
  "active": true,
  "created_at": "2025-03-13T08:45:47+01:00",
  "updated_at": "2025-03-13T08:45:47+01:00",
  "children": []
}

Permissions

Retrieve current user's permissions

Using the account id one can see the currently logged user's permissions

Request

curl -g "https://api.timelyapp.com/1.1/170/users/current/permissions" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer gSkteUCvxVS4Hk69seaneAc9xhIXN81u363h3mC6k_g" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/current/permissions

GET /1.1/170/users/current/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer gSkteUCvxVS4Hk69seaneAc9xhIXN81u363h3mC6k_g

Parameters

Name Description
account_id Account id for which current user's permissions are to be retrieved

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "resource": "account",
    "permissions": [
      "create",
      "read",
      "update",
      "manage_plan",
      "manage_subscriptions",
      "manage_dev"
    ]
  },
  {
    "resource": "company",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "day_property",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "forecast",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "invoice",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "label",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "project",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "report",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "team",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "user",
    "permissions": [
      "create",
      "delete",
      "notify",
      "read",
      "update"
    ]
  }
]

Retrieve user's permissions by id

Using the account id and user id one can see a specific user's permissions

Request

curl -g "https://api.timelyapp.com/1.1/171/users/350/permissions" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Q51fBNf8b3zGNQmLwpQtbLW3OsreNFAfeO1ZVvtnWws" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/:user_id/permissions

GET /1.1/171/users/350/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer Q51fBNf8b3zGNQmLwpQtbLW3OsreNFAfeO1ZVvtnWws

Parameters

Name Description
account_id Account for which user's permissions are required
user_id User whose permissions are required

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "resource": "account",
    "permissions": [
      "create",
      "read",
      "update",
      "manage_plan",
      "manage_subscriptions",
      "manage_dev"
    ]
  },
  {
    "resource": "company",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "day_property",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "forecast",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "invoice",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "label",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "project",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "report",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "team",
    "permissions": [
      "create",
      "delete",
      "read",
      "update"
    ]
  },
  {
    "resource": "user",
    "permissions": [
      "create",
      "delete",
      "notify",
      "read",
      "update"
    ]
  }
]

Projects

Projects contain all the project details on an account. With this API, you can retrieve, update, create or delete a specific project, or list all projects.

Create a project

Request

curl "https://api.timelyapp.com/1.1/177/projects" -d '{"project":{"name":"New Project","rate_type":"project","hour_rate":50.0,"active":true,"deleted":false,"currency_code":"usd","color":"67a3bc","enable_labels":"all","lock_hours_in":0,"description":"Project Description","client_id":129,"budget_type":"M","budget":300,"users":[{"user_id":362}],"budget_recurrence":{"recur":"week","start_date":"2018-09-21","end_date":"2019-09-21","recur_until":"end_date"},"labels":[{"label_id":6,"required":true},{"label_id":7,"required":true},{"label_id":8,"required":false},{"label_id":9,"required":false}]},"name":null}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 39NSSIWBFyW8lfg5f-SXCRUjYnM3YPeNFVRN-6AJxuY" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/projects

POST /1.1/177/projects
Accept: application/json
Content-Type: application/json
Authorization: Bearer 39NSSIWBFyW8lfg5f-SXCRUjYnM3YPeNFVRN-6AJxuY

Parameters

{"project":{"name":"New Project","rate_type":"project","hour_rate":50.0,"active":true,"deleted":false,"currency_code":"usd","color":"67a3bc","enable_labels":"all","lock_hours_in":0,"description":"Project Description","client_id":129,"budget_type":"M","budget":300,"users":[{"user_id":362}],"budget_recurrence":{"recur":"week","start_date":"2018-09-21","end_date":"2019-09-21","recur_until":"end_date"},"labels":[{"label_id":6,"required":true},{"label_id":7,"required":true},{"label_id":8,"required":false},{"label_id":9,"required":false}]},"name":null}
Name Description
project required Project attributes
name required Specifies the project name
color Specifies the project color. Example values: 1976d2, 00796b, 2e7d32, d4e157, ffeb3b, ffb74d, ff8a65, e57373, b72367, 7e57c2 (when omitted, the client color for the project will be used)
client_id required Specifies the numerical client ID
users required Specifies the project users. It should be an array of users, with numerical user IDs and an hour_rate. For example: "users": [{ "user_id": 175551, "hour_rate": 25.0 },{ "user_id": 117861, "hour_rate": 27.0 }]
billable Specifies whether the project is billable or not. It should be “true” or “false”
budget Specifies the budget for the project. It should be numeric value
hour_rate Specifies the hourly rate for the project. It should be numeric valu
rate_type Specifies the hourly rate type for the project. It should be “user” or “project”
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)
budget_recurrence Specifies when a recurring budget will refresh
send_invite Specifies if you want to send a project invite email. It should be “true” or “false”
required_notes Project hours notes to be required for logging
required_labels Project hours with atleast one label to be required for logging
labels Specifies the project labels, should be array of labels with numerical label id and required flag Example: "labels": [{ "label_id": 1, "required": true }, { "label_id": 2, "required": false }]
enable_labels Specifies the way labels will be allowed for logging for the project. It should be “all”, “none” or “custom”
invoice_by_budget Specifies if the project's invoices are based on its budget instead of hours. It should be “true“ or “false“
team_ids Specifies the project teams, should be array of numerical team id's. Example values: team_ids: [3,4,2]

Response

Content-Type: application/json; charset=utf-8
201 Created

{
  "id": 110,
  "active": true,
  "account_id": 177,
  "name": "New Project",
  "description": "Project Description",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "created_at": 1741851949,
  "updated_at": 1741851949,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 129,
    "name": "Aspernatur cum eos qui.",
    "color": "d4e157",
    "active": true,
    "external_id": null,
    "updated_at": "2025-03-13T08:45:49+01:00"
  },
  "required_notes": false,
  "required_labels": false,
  "budget_expired_on": null,
  "has_recurrence": true,
  "enable_labels": "all",
  "default_labels": false,
  "currency": {
    "id": "usd",
    "name": "United States Dollar",
    "iso_code": "USD",
    "symbol": "$",
    "symbol_first": true
  },
  "team_ids": [],
  "budget": 300,
  "budget_type": "M",
  "budget_calculation": "completed",
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "budget_progress": 0.0,
  "budget_percent": 0.0,
  "invoice_by_budget": false,
  "users": [
    {
      "user_id": 362,
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "updated_at": "2025-03-13T08:45:49+01:00",
      "created_at": "2025-03-13T08:45:49+01:00",
      "deleted": false,
      "internal_hour_rate": 0,
      "internal_hour_rate_in_cents": 0
    }
  ],
  "labels": [
    {
      "project_id": 110,
      "label_id": 6,
      "budget": 0,
      "required": true,
      "default": false,
      "updated_at": "2025-03-13T13:15:49+05:30"
    },
    {
      "project_id": 110,
      "label_id": 7,
      "budget": 0,
      "required": true,
      "default": false,
      "updated_at": "2025-03-13T13:15:49+05:30"
    },
    {
      "project_id": 110,
      "label_id": 8,
      "budget": 0,
      "required": false,
      "default": false,
      "updated_at": "2025-03-13T13:15:49+05:30"
    },
    {
      "project_id": 110,
      "label_id": 9,
      "budget": 0,
      "required": false,
      "default": false,
      "updated_at": "2025-03-13T13:15:49+05:30"
    }
  ],
  "label_ids": [
    6,
    7,
    8,
    9
  ],
  "required_label_ids": [
    6,
    7
  ],
  "default_label_ids": [],
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "estimated_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "billed_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "billed_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "unbilled_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "unbilled_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "first_logged_on": null,
  "last_logged_on": null,
  "budget_recurrence": {
    "recur": "week",
    "start_date": "2018-09-21",
    "end_date": "2019-09-21",
    "recur_until": "end_date",
    "days_count": 365,
    "updated_at": "2025-03-13T08:45:49+01:00"
  },
  "created_from": "Timely"
}

Delete a project

Request

curl "https://api.timelyapp.com/1.1/178/projects/111" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer KCVXcg5HTVUy6txM52Nn2mdZomhNfY70zelek8y-Ic8" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/projects/:id

DELETE /1.1/178/projects/111
Accept: application/json
Content-Type: application/json
Authorization: Bearer KCVXcg5HTVUy6txM52Nn2mdZomhNfY70zelek8y-Ic8

Parameters

Name Description
account_id The account ID containing the project you want to delete
id The ID of the project you want to delete

Response

Content-Type: application/json; charset=utf-8
200 OK

{}

List all projects

Note: Admin users can access all projects on an account. Other users can only access the projects they belong to.

Project lists will return your 10000 most recently updated projects. Additionally, you can add the “limit”, “filter”, ”sort” and “order” optional parameters to change the result.

Request

curl -g "https://api.timelyapp.com/1.1/180/projects" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer IHKonCY8wGMao1Qtb89ubH5o-UvhZBbgZxC5pTXp9Y4" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/projects

GET /1.1/180/projects
Accept: application/json
Content-Type: application/json
Authorization: Bearer IHKonCY8wGMao1Qtb89ubH5o-UvhZBbgZxC5pTXp9Y4

Parameters

Name Description
offset Retrieve projects from offset
limit Retrieve number of projects
sort Field to sort projects by - updated_at, id, name (Default updated_at)
order Sorting order - desc, asc (Default desc)
filter Filter projects - mine, active, archived, all (Default mine)
updated_after Retrieve records updated after a certain timestamp
project_ids Retrieve specific projects
external_ids Retrieve specific projects by external ID reference

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 113,
    "active": true,
    "account_id": 180,
    "name": "Timely",
    "description": "Project Description",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "created_at": 1741851950,
    "updated_at": 1741851950,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 132,
      "name": "Qui non in alias.",
      "color": "e57373",
      "active": true,
      "external_id": null,
      "updated_at": "2025-03-13T08:45:50+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "default_labels": false,
    "currency": {
      "id": "usd",
      "name": "United States Dollar",
      "iso_code": "USD",
      "symbol": "$",
      "symbol_first": true
    },
    "team_ids": [],
    "budget": 0,
    "budget_type": "",
    "budget_calculation": "completed",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "budget_progress": 0.0,
    "budget_percent": 0.0,
    "invoice_by_budget": false,
    "users": [
      {
        "user_id": 368,
        "hour_rate": 100.0,
        "hour_rate_in_cents": 10000.0,
        "updated_at": "2025-03-13T08:45:50+01:00",
        "created_at": "2025-03-13T08:45:50+01:00",
        "deleted": false,
        "internal_hour_rate": 0,
        "internal_hour_rate_in_cents": 0
      }
    ],
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "default_label_ids": [],
    "cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0,
      "currency_code": "usd"
    },
    "estimated_cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0,
      "currency_code": "usd"
    },
    "duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "estimated_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "billed_cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0,
      "currency_code": "usd"
    },
    "billed_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "unbilled_cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0,
      "currency_code": "usd"
    },
    "unbilled_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "created_from": "Web"
  }
]

Retrieve a project Retrieve a single project by using its ID.

Request

curl -g "https://api.timelyapp.com/1.1/179/projects/112" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 06kQUaeCNHHiiVNSMBtAKXCaRvSy1FOZcwgM1cb3uj8" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/projects/:id

GET /1.1/179/projects/112
Accept: application/json
Content-Type: application/json
Authorization: Bearer 06kQUaeCNHHiiVNSMBtAKXCaRvSy1FOZcwgM1cb3uj8

Parameters

Name Description
account_id The account ID containing the project you want to retrieve
id The ID of the project you want to retrieve

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 112,
  "active": true,
  "account_id": 179,
  "name": "Timely",
  "description": "Project Description",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "created_at": 1741851950,
  "updated_at": 1741851950,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 131,
    "name": "In ea corrupti impedit.",
    "color": "1976d2",
    "active": true,
    "external_id": null,
    "updated_at": "2025-03-13T08:45:50+01:00"
  },
  "required_notes": false,
  "required_labels": false,
  "budget_expired_on": null,
  "has_recurrence": false,
  "enable_labels": "all",
  "default_labels": false,
  "currency": {
    "id": "usd",
    "name": "United States Dollar",
    "iso_code": "USD",
    "symbol": "$",
    "symbol_first": true
  },
  "team_ids": [],
  "budget": 0,
  "budget_type": "",
  "budget_calculation": "completed",
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "budget_progress": 0.0,
  "budget_percent": 0.0,
  "invoice_by_budget": false,
  "users": [
    {
      "user_id": 366,
      "hour_rate": 100.0,
      "hour_rate_in_cents": 10000.0,
      "updated_at": "2025-03-13T08:45:50+01:00",
      "created_at": "2025-03-13T08:45:50+01:00",
      "deleted": false,
      "internal_hour_rate": 0,
      "internal_hour_rate_in_cents": 0
    }
  ],
  "labels": [],
  "label_ids": [],
  "required_label_ids": [],
  "default_label_ids": [],
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "estimated_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "billed_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "billed_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "unbilled_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "unbilled_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "first_logged_on": null,
  "last_logged_on": null,
  "locked_hours": false,
  "created_from": "Web"
}

Update a project

Request

curl "https://api.timelyapp.com/1.1/182/projects/115" -d '{"project":{"name":"updated project name","name":null}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer HtQwjmsFJF9iaIv3IuXWwCpWbCB-6kFj_7_wtzvE7CA" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/projects/:id

PUT /1.1/182/projects/115
Accept: application/json
Content-Type: application/json
Authorization: Bearer HtQwjmsFJF9iaIv3IuXWwCpWbCB-6kFj_7_wtzvE7CA

Parameters

{"project":{"name":"updated project name","name":null}}
Name Description
id required Project ID
project Project attributes
project[name] required Specifies the project name
project[active] Example values: “true” or “false”. Using “false” changes the project state to “archived”
project[color] Specifies the project color (when omitted, the client color for the project will be used)
project[client_id] required Specifies the numerical client ID
project[users] required Specifies the project users. It should be an array of users, with numerical user IDs and an hour_rate. For example: "users": [{ "user_id": 175551, "hour_rate": 25.0 },{ "user_id": 117861, "hour_rate": 27.0 }]
project[billable] Specifies whether the project is billable or not. It should be “true” or “false”
project[budget] Specifies the budget for the project. It should be numeric value
project[hour_rate] Specifies the hourly rate for the project. It should be numeric value
project[rate_type] Specifies the hourly rate type for the project. It should be “user” or “project”
project[external_id] The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)
project[send_invite] Specifies if you want to send a project invite email. It should be “true” or “false”
project[required_notes] Project hours notes to be required for logging
project[required_labels] Project hours with atleast one label to be required for logging
project[enable_labels] Specifies the way labels will be allowed for logging the project. It should be “all”, “none” or “custom”
project[invoice_by_budget] Specifies if the project's invoices are based on its budget instead of hours. It should be “true“ or “false“.
update_existing_hours Specifies if the rates of existing hours in the project should be updated. It should be "true" or "false". Default: true
update_unbilled_only Specifies if only the rates of unbilled hours in the project should be updated. It is ignored if "update_existing_hours" is false. It should be "true" or "false". Default: false
team_ids Specifies the project teams, should be array of numerical team id's. Example values: team_ids: [3,4,2]

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 115,
  "active": true,
  "account_id": 182,
  "name": "Timely",
  "description": "Project Description",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "created_at": 1741851951,
  "updated_at": 1741851951,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 134,
    "name": "Velit similique error consectetur.",
    "color": "ffeb3b",
    "active": true,
    "external_id": null,
    "updated_at": "2025-03-13T08:45:51+01:00"
  },
  "required_notes": false,
  "required_labels": false,
  "budget_expired_on": null,
  "has_recurrence": false,
  "enable_labels": "none",
  "default_labels": false,
  "currency": {
    "id": "usd",
    "name": "United States Dollar",
    "iso_code": "USD",
    "symbol": "$",
    "symbol_first": true
  },
  "team_ids": [],
  "budget": 0,
  "budget_type": "",
  "budget_calculation": "pending",
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "budget_progress": 0.0,
  "budget_percent": 0.0,
  "invoice_by_budget": false,
  "users": [
    {
      "user_id": 372,
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "updated_at": "2025-03-13T08:45:51+01:00",
      "created_at": "2025-03-13T08:45:51+01:00",
      "deleted": false,
      "internal_hour_rate": 0,
      "internal_hour_rate_in_cents": 0
    }
  ],
  "labels": [],
  "label_ids": [],
  "required_label_ids": [],
  "default_label_ids": [],
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "estimated_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "billed_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "billed_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "unbilled_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0,
    "currency_code": "usd"
  },
  "unbilled_duration": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "first_logged_on": null,
  "last_logged_on": null,
  "created_from": "Web"
}

Reports

Report on activity across your business, including individual and team performance. Export report data from JSON to a format of your choice. Note: .XLS, .CSV and .PDF report formats can only be downloaded from the web UI, not the API.

All Reports For a normal user accessing all account reports.

Note:

1) If start_date and end_date parameters are not passed, the period will default to the beginning-to-end of a month. 2) If user and project parameters are not passed, by default a normal user will get all reports on an account, and a limited user will only get reports they have created. 3) Only normal users can access reports created by other users on an account. Limited users can only access reports they have created. 4) Only normal users can access reports for other projects on an account. Limited users can only access reports for projects they have created.

Request

curl "https://api.timelyapp.com/1.1/218/reports" -d '{"user_ids":"477","since":"2018-01-01","until":"2019-01-01","project_ids":"200"}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Bd1NuwN7OQAM57JgU1KW5Qmzr5_QzexbBiAAlwMLKcc" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/reports

POST /1.1/218/reports
Accept: application/json
Content-Type: application/json
Authorization: Bearer Bd1NuwN7OQAM57JgU1KW5Qmzr5_QzexbBiAAlwMLKcc

Parameters

{"user_ids":"477","since":"2018-01-01","until":"2019-01-01","project_ids":"200"}
Name Description
account_id The account ID containing the report you want to retrieve
user_ids Specifies the users for which you want reports. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861"
since Specifies the start date for a report: For example: "since" : "Jan 01, 2014"
until Specifies the end date for a report. For example: "until" : "Dec 31, 2014"
project_ids Specifies the projects for which you want reports. Numerical project IDs should be separated by a comma, like so: "project_ids": "1751,1171"
billed Specifies whether you want to report to show estimated or billed events. For example: "billed": false or "billed": true
label_ids Specifies the labels pertaining to a report you want to see. Numerical label IDs should be separated by a comma, like so: "label_ids": [751,117] or "751,117". Result will include any of provided values.

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 170,
    "name": "Qui sequi ad consequatur.",
    "projects": [
      {
        "id": 200,
        "active": true,
        "account_id": 218,
        "name": "Timely",
        "description": "Project Description",
        "color": "67a3bc",
        "rate_type": "project",
        "billable": true,
        "created_at": 1741851960,
        "updated_at": 1741851960,
        "external_id": null,
        "budget_scope": null,
        "client": {
          "id": 170,
          "name": "Qui sequi ad consequatur.",
          "color": "00796b",
          "active": true,
          "external_id": null,
          "updated_at": "2025-03-13T08:46:00+01:00"
        },
        "required_notes": false,
        "required_labels": false,
        "budget_expired_on": null,
        "has_recurrence": false,
        "enable_labels": "all",
        "default_labels": false,
        "currency": {
          "id": "usd",
          "name": "United States Dollar",
          "iso_code": "USD",
          "symbol": "$",
          "symbol_first": true
        },
        "team_ids": [],
        "budget": 0,
        "budget_type": "",
        "budget_calculation": "completed",
        "hour_rate": 50.0,
        "hour_rate_in_cents": 5000.0,
        "budget_progress": 0.0,
        "budget_percent": 0.0,
        "invoice_by_budget": false,
        "duration": {
          "hours": 5,
          "minutes": 0,
          "seconds": 0,
          "formatted": "05:00",
          "total_hours": 5.0,
          "total_seconds": 18000,
          "total_minutes": 300
        },
        "estimated_duration": {
          "hours": 8,
          "minutes": 0,
          "seconds": 0,
          "formatted": "08:00",
          "total_hours": 8.0,
          "total_seconds": 28800,
          "total_minutes": 480
        },
        "billed_duration": {
          "hours": 0,
          "minutes": 0,
          "seconds": 0,
          "formatted": "00:00",
          "total_hours": 0.0,
          "total_seconds": 0,
          "total_minutes": 0
        },
        "unbilled_duration": {
          "hours": 5,
          "minutes": 0,
          "seconds": 0,
          "formatted": "05:00",
          "total_hours": 5.0,
          "total_seconds": 18000,
          "total_minutes": 300
        },
        "billable_duration": {
          "hours": 5,
          "minutes": 0,
          "seconds": 0,
          "formatted": "05:00",
          "total_hours": 5.0,
          "total_seconds": 18000,
          "total_minutes": 300
        },
        "non_billable_duration": {
          "hours": 0,
          "minutes": 0,
          "seconds": 0,
          "formatted": "00:00",
          "total_hours": 0.0,
          "total_seconds": 0,
          "total_minutes": 0
        },
        "cost": {
          "fractional": 50000,
          "formatted": "$500.00",
          "amount": 500.0,
          "currency_code": "usd"
        },
        "estimated_cost": {
          "fractional": 80000,
          "formatted": "$800.00",
          "amount": 800.0,
          "currency_code": "usd"
        },
        "billed_cost": {
          "fractional": 0,
          "formatted": "$0.00",
          "amount": 0.0,
          "currency_code": "usd"
        },
        "unbilled_cost": {
          "fractional": 50000,
          "formatted": "$500.00",
          "amount": 500.0,
          "currency_code": "usd"
        },
        "internal_cost": {
          "fractional": 75000,
          "formatted": "$750.00",
          "amount": 750.0,
          "currency_code": "usd"
        },
        "profit": {
          "fractional": -25000,
          "formatted": "$-250.00",
          "amount": -250.0,
          "currency_code": "usd"
        },
        "profitability": 0,
        "created_from": "Web"
      }
    ],
    "duration": {
      "hours": 5,
      "minutes": 0,
      "seconds": 0,
      "formatted": "05:00",
      "total_hours": 5.0,
      "total_seconds": 18000,
      "total_minutes": 300
    },
    "estimated_duration": {
      "hours": 8,
      "minutes": 0,
      "seconds": 0,
      "formatted": "08:00",
      "total_hours": 8.0,
      "total_seconds": 28800,
      "total_minutes": 480
    },
    "billed_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "unbilled_duration": {
      "hours": 5,
      "minutes": 0,
      "seconds": 0,
      "formatted": "05:00",
      "total_hours": 5.0,
      "total_seconds": 18000,
      "total_minutes": 300
    },
    "billable_duration": {
      "hours": 5,
      "minutes": 0,
      "seconds": 0,
      "formatted": "05:00",
      "total_hours": 5.0,
      "total_seconds": 18000,
      "total_minutes": 300
    },
    "non_billable_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "cost": {
      "fractional": 50000,
      "formatted": "$500.00",
      "amount": 500.0,
      "currency_code": "usd"
    },
    "estimated_cost": {
      "fractional": 80000,
      "formatted": "$800.00",
      "amount": 800.0,
      "currency_code": "usd"
    },
    "billed_cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0,
      "currency_code": "usd"
    },
    "unbilled_cost": {
      "fractional": 50000,
      "formatted": "$500.00",
      "amount": 500.0,
      "currency_code": "usd"
    },
    "internal_cost": {
      "fractional": 75000,
      "formatted": "$750.00",
      "amount": 750.0,
      "currency_code": "usd"
    },
    "profit": {
      "fractional": -25000,
      "formatted": "$-250.00",
      "amount": -250.0,
      "currency_code": "usd"
    },
    "profitability": 0
  }
]

Filter reports

Use filter endpoints with parameters to limit returned data, so you only see the values that you need.

Request

curl "https://api.timelyapp.com/1.1/219/reports/filter" -d '{"user_ids":"479","since":"2018-01-01","until":"2019-01-01","project_ids":"201"}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer gABJdcKMReMJ0yWT5Yrl6BV_i_IYAostBniVISiOuOw" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/reports/filter

POST /1.1/219/reports/filter
Accept: application/json
Content-Type: application/json
Authorization: Bearer gABJdcKMReMJ0yWT5Yrl6BV_i_IYAostBniVISiOuOw

Parameters

{"user_ids":"479","since":"2018-01-01","until":"2019-01-01","project_ids":"201"}
Name Description
billed Retrieve billed hours only. Example: billed=true
label_ids Specifies the label IDs of the hours you want to retrieve. Label IDs should be a numerical array, like so: label_ids: [3,4,2] or "3,4,2". Result will include any of provided values.
project_ids Specifies the project IDs of the hours you want to retrieve. Project IDs should be a numerical array, like so: project_ids: [3,4,2]
since The start date of a report. For example: 'since=2019-01-01'
team_ids Specifies the team IDs of the hours you want to retrieve. Team IDs should be a numerical array, like so: team_ids: [3,4,2]
until The end date of a report. For example: 'until=2019-12-31''
user_ids Specifies the user IDs of the hours you want to retrieve. User IDs should be a numerical array, like so: user_ids: [3,4,2]
group_by Specifies how to group the hours. Default: group_by: ["clients", "users", "labels", "days", "teams"]
scope Retrieve events only. For example: 'scope=events'
offset Retrieve records from offset (Default 0).
limit Retrieve number of records. Max 100 records.
page Page number (Default 1).
locked Retrieve locked hours only. Example: locked=true

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "multiple_currency_report": false,
  "totals": {
    "duration": {
      "hours": 5,
      "minutes": 0,
      "seconds": 0,
      "formatted": "05:00",
      "total_hours": 5.0,
      "total_seconds": 18000,
      "total_minutes": 300
    },
    "estimated_duration": {
      "hours": 8,
      "minutes": 0,
      "seconds": 0,
      "formatted": "08:00",
      "total_hours": 8.0,
      "total_seconds": 28800,
      "total_minutes": 480
    },
    "billed_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "unbilled_duration": {
      "hours": 5,
      "minutes": 0,
      "seconds": 0,
      "formatted": "05:00",
      "total_hours": 5.0,
      "total_seconds": 18000,
      "total_minutes": 300
    },
    "billable_duration": {
      "hours": 5,
      "minutes": 0,
      "seconds": 0,
      "formatted": "05:00",
      "total_hours": 5.0,
      "total_seconds": 18000,
      "total_minutes": 300
    },
    "non_billable_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    },
    "cost": {
      "fractional": 50000,
      "formatted": "$500.00",
      "amount": 500.0,
      "currency_code": "usd"
    },
    "estimated_cost": {
      "fractional": 80000,
      "formatted": "$800.00",
      "amount": 800.0,
      "currency_code": "usd"
    },
    "billed_cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0,
      "currency_code": "usd"
    },
    "unbilled_cost": {
      "fractional": 50000,
      "formatted": "$500.00",
      "amount": 500.0,
      "currency_code": "usd"
    },
    "internal_cost": {
      "fractional": 75000,
      "formatted": "$750.00",
      "amount": 750.0,
      "currency_code": "usd"
    },
    "profit": {
      "fractional": -25000,
      "formatted": "$-250.00",
      "amount": -250.0,
      "currency_code": "usd"
    },
    "profitability": 0
  },
  "clients": [
    {
      "id": 171,
      "name": "Vel quia perferendis est.",
      "projects": [
        {
          "id": 201,
          "active": true,
          "account_id": 219,
          "name": "Timely",
          "description": "Project Description",
          "color": "67a3bc",
          "rate_type": "project",
          "billable": true,
          "created_at": 1741851960,
          "updated_at": 1741851960,
          "external_id": null,
          "budget_scope": null,
          "client": {
            "id": 171,
            "name": "Vel quia perferendis est.",
            "color": "e57373",
            "active": true,
            "external_id": null,
            "updated_at": "2025-03-13T08:46:00+01:00"
          },
          "required_notes": false,
          "required_labels": false,
          "budget_expired_on": null,
          "has_recurrence": false,
          "enable_labels": "all",
          "default_labels": false,
          "currency": {
            "id": "usd",
            "name": "United States Dollar",
            "iso_code": "USD",
            "symbol": "$",
            "symbol_first": true
          },
          "team_ids": [],
          "budget": 0,
          "budget_type": "",
          "budget_calculation": "completed",
          "hour_rate": 50.0,
          "hour_rate_in_cents": 5000.0,
          "budget_progress": 0.0,
          "budget_percent": 0.0,
          "invoice_by_budget": false,
          "duration": {
            "hours": 5,
            "minutes": 0,
            "seconds": 0,
            "formatted": "05:00",
            "total_hours": 5.0,
            "total_seconds": 18000,
            "total_minutes": 300
          },
          "estimated_duration": {
            "hours": 8,
            "minutes": 0,
            "seconds": 0,
            "formatted": "08:00",
            "total_hours": 8.0,
            "total_seconds": 28800,
            "total_minutes": 480
          },
          "billed_duration": {
            "hours": 0,
            "minutes": 0,
            "seconds": 0,
            "formatted": "00:00",
            "total_hours": 0.0,
            "total_seconds": 0,
            "total_minutes": 0
          },
          "unbilled_duration": {
            "hours": 5,
            "minutes": 0,
            "seconds": 0,
            "formatted": "05:00",
            "total_hours": 5.0,
            "total_seconds": 18000,
            "total_minutes": 300
          },
          "billable_duration": {
            "hours": 5,
            "minutes": 0,
            "seconds": 0,
            "formatted": "05:00",
            "total_hours": 5.0,
            "total_seconds": 18000,
            "total_minutes": 300
          },
          "non_billable_duration": {
            "hours": 0,
            "minutes": 0,
            "seconds": 0,
            "formatted": "00:00",
            "total_hours": 0.0,
            "total_seconds": 0,
            "total_minutes": 0
          },
          "cost": {
            "fractional": 50000,
            "formatted": "$500.00",
            "amount": 500.0,
            "currency_code": "usd"
          },
          "estimated_cost": {
            "fractional": 80000,
            "formatted": "$800.00",
            "amount": 800.0,
            "currency_code": "usd"
          },
          "billed_cost": {
            "fractional": 0,
            "formatted": "$0.00",
            "amount": 0.0,
            "currency_code": "usd"
          },
          "unbilled_cost": {
            "fractional": 50000,
            "formatted": "$500.00",
            "amount": 500.0,
            "currency_code": "usd"
          },
          "internal_cost": {
            "fractional": 75000,
            "formatted": "$750.00",
            "amount": 750.0,
            "currency_code": "usd"
          },
          "profit": {
            "fractional": -25000,
            "formatted": "$-250.00",
            "amount": -250.0,
            "currency_code": "usd"
          },
          "profitability": 0,
          "created_from": "Web"
        }
      ],
      "duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "estimated_duration": {
        "hours": 8,
        "minutes": 0,
        "seconds": 0,
        "formatted": "08:00",
        "total_hours": 8.0,
        "total_seconds": 28800,
        "total_minutes": 480
      },
      "billed_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "unbilled_duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "billable_duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "non_billable_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0,
        "currency_code": "usd"
      },
      "estimated_cost": {
        "fractional": 80000,
        "formatted": "$800.00",
        "amount": 800.0,
        "currency_code": "usd"
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0,
        "currency_code": "usd"
      },
      "unbilled_cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0,
        "currency_code": "usd"
      },
      "internal_cost": {
        "fractional": 75000,
        "formatted": "$750.00",
        "amount": 750.0,
        "currency_code": "usd"
      },
      "profit": {
        "fractional": -25000,
        "formatted": "$-250.00",
        "amount": -250.0,
        "currency_code": "usd"
      },
      "profitability": 0
    }
  ],
  "users": [
    {
      "id": 479,
      "email": "marijazlwalwvc@timelyapp.com",
      "name": "Marija Petrovic",
      "time_zone": "Europe/Paris",
      "updated_at": 1741851960,
      "active": false,
      "deleted": false,
      "memory_onboarded": true,
      "day_view_onboarded": true,
      "last_received_memories_date": null,
      "date_format": "dmy",
      "time_format": "24",
      "memory_retention_days": null,
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/b5a467d895d46e575edc24cd9aeae7f2?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/b5a467d895d46e575edc24cd9aeae7f2?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/b5a467d895d46e575edc24cd9aeae7f2?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/b5a467d895d46e575edc24cd9aeae7f2?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/b5a467d895d46e575edc24cd9aeae7f2?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "estimated_duration": {
        "hours": 8,
        "minutes": 0,
        "seconds": 0,
        "formatted": "08:00",
        "total_hours": 8.0,
        "total_seconds": 28800,
        "total_minutes": 480
      },
      "billed_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "unbilled_duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "billable_duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "non_billable_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0,
        "currency_code": "usd"
      },
      "estimated_cost": {
        "fractional": 80000,
        "formatted": "$800.00",
        "amount": 800.0,
        "currency_code": "usd"
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0,
        "currency_code": "usd"
      },
      "unbilled_cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0,
        "currency_code": "usd"
      },
      "internal_cost": {
        "fractional": 75000,
        "formatted": "$750.00",
        "amount": 750.0,
        "currency_code": "usd"
      },
      "profit": {
        "fractional": -25000,
        "formatted": "$-250.00",
        "amount": -250.0,
        "currency_code": "usd"
      },
      "profitability": 0,
      "capacity": {
        "hours": 2096,
        "minutes": 0,
        "seconds": 0.0,
        "formatted": "2096:00",
        "total_hours": 2096.0,
        "total_seconds": 7545600.0,
        "total_minutes": 125760.0
      },
      "overtime": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "undertime": {
        "hours": 2091,
        "minutes": 0,
        "seconds": 0.0,
        "formatted": "2091:00",
        "total_hours": 2091.0,
        "total_seconds": 7527600.0,
        "total_minutes": 125460.0
      }
    }
  ],
  "labels": [
    {
      "id": 0,
      "name": "Untagged",
      "sequence": -1,
      "parent_id": null,
      "emoji": "https://emoji.memorycdn.com/tw64/1f3f7.png",
      "active": true,
      "created_at": null,
      "updated_at": null,
      "children": [],
      "duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "estimated_duration": {
        "hours": 8,
        "minutes": 0,
        "seconds": 0,
        "formatted": "08:00",
        "total_hours": 8.0,
        "total_seconds": 28800,
        "total_minutes": 480
      },
      "billed_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "unbilled_duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "billable_duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "non_billable_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0,
        "currency_code": "usd"
      },
      "estimated_cost": {
        "fractional": 80000,
        "formatted": "$800.00",
        "amount": 800.0,
        "currency_code": "usd"
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0,
        "currency_code": "usd"
      },
      "unbilled_cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0,
        "currency_code": "usd"
      },
      "internal_cost": {
        "fractional": 75000,
        "formatted": "$750.00",
        "amount": 750.0,
        "currency_code": "usd"
      },
      "profit": {
        "fractional": -25000,
        "formatted": "$-250.00",
        "amount": -250.0,
        "currency_code": "usd"
      },
      "profitability": 0
    }
  ],
  "days": [
    {
      "day": "2018-01-02",
      "duration": {
        "hours": 2,
        "minutes": 30,
        "seconds": 0,
        "formatted": "02:30",
        "total_hours": 2.5,
        "total_seconds": 9000,
        "total_minutes": 150
      },
      "estimated_duration": {
        "hours": 4,
        "minutes": 0,
        "seconds": 0,
        "formatted": "04:00",
        "total_hours": 4.0,
        "total_seconds": 14400,
        "total_minutes": 240
      },
      "billed_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "unbilled_duration": {
        "hours": 2,
        "minutes": 30,
        "seconds": 0,
        "formatted": "02:30",
        "total_hours": 2.5,
        "total_seconds": 9000,
        "total_minutes": 150
      },
      "billable_duration": {
        "hours": 2,
        "minutes": 30,
        "seconds": 0,
        "formatted": "02:30",
        "total_hours": 2.5,
        "total_seconds": 9000,
        "total_minutes": 150
      },
      "non_billable_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.0,
        "currency_code": "usd"
      },
      "estimated_cost": {
        "fractional": 40000,
        "formatted": "$400.00",
        "amount": 400.0,
        "currency_code": "usd"
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0,
        "currency_code": "usd"
      },
      "unbilled_cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.0,
        "currency_code": "usd"
      },
      "internal_cost": {
        "fractional": 37500,
        "formatted": "$375.00",
        "amount": 375.0,
        "currency_code": "usd"
      },
      "profit": {
        "fractional": -12500,
        "formatted": "$-125.00",
        "amount": -125.0,
        "currency_code": "usd"
      },
      "profitability": 0
    },
    {
      "day": "2018-01-01",
      "duration": {
        "hours": 2,
        "minutes": 30,
        "seconds": 0,
        "formatted": "02:30",
        "total_hours": 2.5,
        "total_seconds": 9000,
        "total_minutes": 150
      },
      "estimated_duration": {
        "hours": 4,
        "minutes": 0,
        "seconds": 0,
        "formatted": "04:00",
        "total_hours": 4.0,
        "total_seconds": 14400,
        "total_minutes": 240
      },
      "billed_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "unbilled_duration": {
        "hours": 2,
        "minutes": 30,
        "seconds": 0,
        "formatted": "02:30",
        "total_hours": 2.5,
        "total_seconds": 9000,
        "total_minutes": 150
      },
      "billable_duration": {
        "hours": 2,
        "minutes": 30,
        "seconds": 0,
        "formatted": "02:30",
        "total_hours": 2.5,
        "total_seconds": 9000,
        "total_minutes": 150
      },
      "non_billable_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.0,
        "currency_code": "usd"
      },
      "estimated_cost": {
        "fractional": 40000,
        "formatted": "$400.00",
        "amount": 400.0,
        "currency_code": "usd"
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0,
        "currency_code": "usd"
      },
      "unbilled_cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.0,
        "currency_code": "usd"
      },
      "internal_cost": {
        "fractional": 37500,
        "formatted": "$375.00",
        "amount": 375.0,
        "currency_code": "usd"
      },
      "profit": {
        "fractional": -12500,
        "formatted": "$-125.00",
        "amount": -125.0,
        "currency_code": "usd"
      },
      "profitability": 0
    }
  ],
  "teams": [
    {
      "id": 0,
      "name": "No team",
      "color": "866b9c",
      "emoji": "https://emoji.memorycdn.com/tw64/1f465.png",
      "external_id": null,
      "duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "estimated_duration": {
        "hours": 8,
        "minutes": 0,
        "seconds": 0,
        "formatted": "08:00",
        "total_hours": 8.0,
        "total_seconds": 28800,
        "total_minutes": 480
      },
      "billed_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "unbilled_duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "billable_duration": {
        "hours": 5,
        "minutes": 0,
        "seconds": 0,
        "formatted": "05:00",
        "total_hours": 5.0,
        "total_seconds": 18000,
        "total_minutes": 300
      },
      "non_billable_duration": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0,
        "currency_code": "usd"
      },
      "estimated_cost": {
        "fractional": 80000,
        "formatted": "$800.00",
        "amount": 800.0,
        "currency_code": "usd"
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0,
        "currency_code": "usd"
      },
      "unbilled_cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0,
        "currency_code": "usd"
      },
      "internal_cost": {
        "fractional": 75000,
        "formatted": "$750.00",
        "amount": 750.0,
        "currency_code": "usd"
      },
      "profit": {
        "fractional": -25000,
        "formatted": "$-250.00",
        "amount": -250.0,
        "currency_code": "usd"
      },
      "profitability": 0,
      "capacity": {
        "hours": 2096,
        "minutes": 0,
        "seconds": 0.0,
        "formatted": "2096:00",
        "total_hours": 2096.0,
        "total_seconds": 7545600.0,
        "total_minutes": 125760.0
      },
      "overtime": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "formatted": "00:00",
        "total_hours": 0.0,
        "total_seconds": 0,
        "total_minutes": 0
      },
      "undertime": {
        "hours": 2091,
        "minutes": 0,
        "seconds": 0.0,
        "formatted": "2091:00",
        "total_hours": 2091.0,
        "total_seconds": 7527600.0,
        "total_minutes": 125460.0
      }
    }
  ]
}

Roles

List roles

Note: default attribute shows which role to select by default

Request

curl -g "https://api.timelyapp.com/1.1/220/roles" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer oXcq058MGEMA3n0jsc4zDVxccejVVUp7DbJGPNWNR7g" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/roles

GET /1.1/220/roles
Accept: application/json
Content-Type: application/json
Authorization: Bearer oXcq058MGEMA3n0jsc4zDVxccejVVUp7DbJGPNWNR7g

Parameters

Name Description
account_id Account id for which roles are required

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 877,
    "name": "admin",
    "display_name": "Admin",
    "description": "Can see, create and edit all hours, projects and teams.",
    "scopes": [
      {
        "name": "hide_hourly_rate",
        "display_name": "Hide billable rate",
        "description": "Hide hourly rates for this user",
        "default": false,
        "options": [
          false
        ]
      },
      {
        "name": "hide_internal_hourly_rate",
        "display_name": "Hide cost rate",
        "description": "Hide internal hourly rates for this user",
        "default": false,
        "options": [
          false
        ]
      }
    ],
    "default": false,
    "allowed_to_invite": true
  },
  {
    "id": 879,
    "name": "employee",
    "display_name": "Employee",
    "description": "Can only see, log and edit their own hours.",
    "scopes": [
      {
        "name": "hide_hourly_rate",
        "display_name": "Hide billable rate",
        "description": "Hide hourly rates for this user",
        "default": false,
        "options": [
          true,
          false
        ]
      },
      {
        "name": "hide_internal_hourly_rate",
        "display_name": "Hide cost rate",
        "description": "Hide internal hourly rates for this user",
        "default": true,
        "options": [
          true,
          false
        ]
      }
    ],
    "default": false,
    "allowed_to_invite": true
  },
  {
    "id": 878,
    "name": "manager",
    "display_name": "Manager",
    "description": "Can see, log and edit hours for anyone on the same project as them.",
    "scopes": [
      {
        "name": "hide_hourly_rate",
        "display_name": "Hide billable rate",
        "description": "Hide hourly rates for this user",
        "default": false,
        "options": [
          true,
          false
        ]
      },
      {
        "name": "hide_internal_hourly_rate",
        "display_name": "Hide cost rate",
        "description": "Hide internal hourly rates for this user",
        "default": true,
        "options": [
          true,
          false
        ]
      }
    ],
    "default": true,
    "allowed_to_invite": true
  },
  {
    "id": 880,
    "name": "team_lead",
    "display_name": "Team Lead",
    "description": "Can see, log and edit hours for anyone from the team they lead",
    "scopes": [
      {
        "name": "hide_hourly_rate",
        "display_name": "Hide billable rate",
        "description": "Hide hourly rates for this user",
        "default": false,
        "options": [
          true,
          false
        ]
      },
      {
        "name": "hide_internal_hourly_rate",
        "display_name": "Hide cost rate",
        "description": "Hide internal hourly rates for this user",
        "default": true,
        "options": [
          true,
          false
        ]
      }
    ],
    "default": false,
    "allowed_to_invite": false
  }
]

Teams

The team object shows all teams available on an account.

Create a team

Request

curl "https://api.timelyapp.com/1.1/243/teams" -d '{"name":null,"team":{"name":"Timely","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":527,"lead":true},{"user_id":529,"lead":false}]}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer cX-cofMp02UVDVmfQirEWdqpq1HyX15bQ5MgAO2jf-4" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/teams

POST /1.1/243/teams
Accept: application/json
Content-Type: application/json
Authorization: Bearer cX-cofMp02UVDVmfQirEWdqpq1HyX15bQ5MgAO2jf-4

Parameters

{"name":null,"team":{"name":"Timely","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":527,"lead":true},{"user_id":529,"lead":false}]}}
Name Description
name required Specifies the team name
emoji Specifies the emoji url for a team
color Specifies the project color for a team
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)
users required Specifies users and their role within a team. For example: users:[{'user_id': 1, 'lead': true}]

Response

Content-Type: application/json; charset=utf-8
201 Created

{
  "id": 1,
  "name": "Timely",
  "color": "67a3bc",
  "emoji": "http://path.to/emoji.png",
  "external_id": null,
  "project_ids": [],
  "user_ids": [
    527,
    529
  ],
  "users": [
    {
      "id": 1,
      "user_id": 527,
      "team_id": 1,
      "lead": true,
      "hide_hours": false
    },
    {
      "id": 2,
      "user_id": 529,
      "team_id": 1,
      "lead": false,
      "hide_hours": false
    }
  ]
}

Delete a team

Request

curl "https://api.timelyapp.com/1.1/244/teams/2" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer cF_auLOOc4GcFhkZSeoMoCY5JRrvbg4hTE2qZwIZZkk" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/teams/:id

DELETE /1.1/244/teams/2
Accept: application/json
Content-Type: application/json
Authorization: Bearer cF_auLOOc4GcFhkZSeoMoCY5JRrvbg4hTE2qZwIZZkk

Parameters

Name Description
account_id The account ID containing the team you want to delete
id The ID of the team you want to delete
delete_project_users Specifies if associated users should be removed from team projects. For example: "delete_project_users":true. Default: false

Response

Content-Type: application/json; charset=utf-8
200 OK

{}

List all teams

Request

curl -g "https://api.timelyapp.com/1.1/246/teams" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer m786qQgxOl3C3C_W3mUBhVaH66G9nyvq8AXhB5JA49Y" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/teams

GET /1.1/246/teams
Accept: application/json
Content-Type: application/json
Authorization: Bearer m786qQgxOl3C3C_W3mUBhVaH66G9nyvq8AXhB5JA49Y

Parameters

Name Description
page Page number (Default 1)
per_page Records per page (Default 50)
order Sorting order on name
filter Filter teams - mine, all

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 4,
    "name": "Timely",
    "color": "67a3bc",
    "emoji": "http://path.to/emoji.png",
    "external_id": null,
    "project_ids": [],
    "user_ids": [],
    "users": []
  }
]

Retrieve a team

Request

curl -g "https://api.timelyapp.com/1.1/245/teams/3" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ldlhnJ-X13ZoNzImu44X1wf2YHdpN04dSlarEJOcVFo" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/teams/:id

GET /1.1/245/teams/3
Accept: application/json
Content-Type: application/json
Authorization: Bearer ldlhnJ-X13ZoNzImu44X1wf2YHdpN04dSlarEJOcVFo

Parameters

Name Description
account_id The account ID containing the team you want to retrieve
id The ID of the team you want to retrieve

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 3,
  "name": "Timely",
  "color": "67a3bc",
  "emoji": "http://path.to/emoji.png",
  "external_id": null,
  "project_ids": [],
  "user_ids": [],
  "users": []
}

Update a team

Request

curl "https://api.timelyapp.com/1.1/247/teams/5" -d '{"name":null,"team":{"name":"Backend","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":536,"lead":true}]}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer r-iO4umvUnvRnJSKtQJfGjhgDvZkAaKupkHaEntYkSA" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/teams/:id

PUT /1.1/247/teams/5
Accept: application/json
Content-Type: application/json
Authorization: Bearer r-iO4umvUnvRnJSKtQJfGjhgDvZkAaKupkHaEntYkSA

Parameters

{"name":null,"team":{"name":"Backend","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":536,"lead":true}]}}
Name Description
name required Specifies the team name
emoji Specifies the emoji url for a team
color Specifies the project color for a team
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)
users required Specific users with their role in the team. Ex: users:[{'user_id': 1, 'lead': true}]
add_users_to_team_projects Specifies if the user should be added to team projects. For example: "add_users_to_team_projects":false. Default: true
delete_users_from_team_projects Specifies if the removed user should be removed from team projects. For example: "delete_users_from_team_projects":true. Default: false

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 5,
  "name": "Backend",
  "color": "67a3bc",
  "emoji": "http://path.to/emoji.png",
  "external_id": null,
  "project_ids": [],
  "user_ids": [
    536
  ],
  "users": [
    {
      "id": 3,
      "user_id": 536,
      "team_id": 5,
      "lead": true,
      "hide_hours": false
    }
  ]
}

UserCapacities

Retrieve capacities

See capacities of multiple users in the account

Request

curl -g "https://api.timelyapp.com/1.1/252/users/capacities" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer wZtGa1jEWyfYU1wi99tNQLroJm_eLb-7uYNF0YOcOIU" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/capacities

GET /1.1/252/users/capacities
Accept: application/json
Content-Type: application/json
Authorization: Bearer wZtGa1jEWyfYU1wi99tNQLroJm_eLb-7uYNF0YOcOIU

Parameters

Name Description
account_id required Account for which users' capacities are required
user_ids Users whose capacities are required
since Fetch capacities after selected date
until Fetch capacities before selected date

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "user_id": 546,
    "capacities": [
      {
        "id": null,
        "weekly_capacity": 40.0,
        "daily_capacity": 8.0,
        "weekdays": "MO,TU,WE,TH,FR",
        "work_days": "MON,TUE,WED,THU,FRI",
        "total_working_days": null,
        "weekly_working_days": 5,
        "current": true,
        "start_date": "1970-01-01",
        "end_date": null
      }
    ]
  }
]

Retrieve user's capacities

Using the user id one can see the user's capacities

Request

curl -g "https://api.timelyapp.com/1.1/251/users/544/capacities" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer qgL9Qg_a8a9YUzfBHAuc90MPrGTVjrahKv8jvSPd598" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/:user_id/capacities

GET /1.1/251/users/544/capacities
Accept: application/json
Content-Type: application/json
Authorization: Bearer qgL9Qg_a8a9YUzfBHAuc90MPrGTVjrahKv8jvSPd598

Parameters

Name Description
account_id required Account for which user's capacities are required
user_id required User whose capacities are required

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": null,
    "weekly_capacity": 40.0,
    "daily_capacity": 8.0,
    "weekdays": "MO,TU,WE,TH,FR",
    "work_days": "MON,TUE,WED,THU,FRI",
    "total_working_days": null,
    "weekly_working_days": 5,
    "current": true,
    "start_date": "1970-01-01",
    "end_date": null
  }
]

Users

An account can have multiple users associated with it. All users have a specific access level, and are usually created by an employer on behalf of an employee.

Create/Invite a user

Note: user_level can have values “normal” or “limited”. A user’s name and email can only be updated by the user themself.

Request

curl "https://api.timelyapp.com/1.1/254/users" -d '{"user":{"name":"Marija Petrovic","email":"marija@timely.com","user_level":"normal","admin":false,"projects":[{"project_id":235,"hour_rate":10}]},"name":null,"admin":{"id":215,"email":"notifications@timelyapp.com","created_at":"2025-03-13T07:46:08.000Z","updated_at":"2025-03-13T07:46:08.000Z","name":"Timely","notifier":true}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer V2TaODsnNBI7k1CGqKYbzK0VloIvtiRR1qAD6CcVeSg" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/users

POST /1.1/254/users
Accept: application/json
Content-Type: application/json
Authorization: Bearer V2TaODsnNBI7k1CGqKYbzK0VloIvtiRR1qAD6CcVeSg

Parameters

{"user":{"name":"Marija Petrovic","email":"marija@timely.com","user_level":"normal","admin":false,"projects":[{"project_id":235,"hour_rate":10}]},"name":null,"admin":{"id":215,"email":"notifications@timelyapp.com","created_at":"2025-03-13T07:46:08.000Z","updated_at":"2025-03-13T07:46:08.000Z","name":"Timely","notifier":true}}
Name Description
user required User attributes
name required Specifies the user name
email required Specifies the user email
projects Description: Specifies the projects that the user will be part of. For example: "projects": [ {"project_id": 11 , "hour_rate": 10 }, {"project_id": 12 , "hour_rate": 20 }]
role_id required Specifies the user's role in the account
user_level (Deprecated) Specifies the user level; either “normal” or “limited”. The default is "normal". For example: "user_level": "normal"
admin (Deprecated) Specifies the user is an admin. In this case user_level should be “normal”. For example: "admin": "true"
external_id The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters)
weekly_capacity Specifies the user's weekly hour capacity. The default is account's weekly capacity. To avoid rounding issues, values are allowed upto 1 decimal place and divisible by 5.
add_to_all_projects Specifies whether the user should be added to all projects in the account. For example: "add_to_all_projects":true
internal_hour_rate Specifies the internal hourly rate for users in the account
hide_internal_hourly_rate The hide_internal_hourly_rate hides the internal hourly rate for users in the account. The default is true. For example: "hide_internal_hourly_rate": true
team_ids Specifies the teams that the user will be part of, should be array of numerical team id's. Example values: team_ids: [3,4,2]
add_team_users_to_projects Specifies if the user should be added to team projects Specified in team_ids. For example: "add_team_users_to_projects":false. Default: true

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 552,
  "email": "marija@timely.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": false,
  "memory_onboarded": false,
  "created_at": 1741851968,
  "updated_at": 1741851968,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Etc/UTC",
  "memory_retention_days": null,
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
  },
  "type": "User",
  "work_days": "MON,TUE,WED,THU,FRI",
  "weekdays": "MO,TU,WE,TH,FR",
  "weekly_capacity": 40.0,
  "user_level": "manager",
  "admin": false,
  "hide_hourly_rate": false,
  "hide_internal_hourly_rate": false,
  "deleted": false,
  "default_hour_rate": 0.0,
  "internal_hour_rate": 0.0,
  "role_id": 1014,
  "role": {
    "id": 1014,
    "name": "manager"
  }
}

Delete a user

Request

curl "https://api.timelyapp.com/1.1/255/users/553" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer JbJhZmg-HWyuLzHvudzxKagr8F8ikEsbtVFc8Vqk_IA" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/users/:id

DELETE /1.1/255/users/553
Accept: application/json
Content-Type: application/json
Authorization: Bearer JbJhZmg-HWyuLzHvudzxKagr8F8ikEsbtVFc8Vqk_IA

Parameters

Name Description
account_id The account ID containing the user you want to delete
id The ID of the user you want to delete

Response

Content-Type: application/json; charset=utf-8
200 OK

{}

List all users

Note: The user list will return the 100 most recently updated users.

Request

curl -g "https://api.timelyapp.com/1.1/258/users" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer vPn-mCFFW-67VRpqXYkPdKAuZSTVa8DHoUOOj1Az5d8" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users

GET /1.1/258/users
Accept: application/json
Content-Type: application/json
Authorization: Bearer vPn-mCFFW-67VRpqXYkPdKAuZSTVa8DHoUOOj1Az5d8

Parameters

Name Description
account_id The account ID containing the users you want to retrieve
limit Retrieve a limited number of users (Default 100)
offset Retrieve users from offset
order Sorting order on updated_at - desc, asc (Default desc)
filter Filter users - active, deleted (Default active)

Response

Content-Type: application/json; charset=utf-8
200 OK

[
  {
    "id": 559,
    "email": "marijatlefcrex@timelyapp.com",
    "name": "Marija Petrovic",
    "active": false,
    "day_view_onboarded": true,
    "memory_onboarded": true,
    "created_at": 1741851969,
    "updated_at": 1741851969,
    "last_received_memories_date": null,
    "sign_in_count": null,
    "external_id": null,
    "time_zone": "Europe/Paris",
    "memory_retention_days": null,
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/9b006b129e4927a32c8784f962a7cac5?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/9b006b129e4927a32c8784f962a7cac5?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "medium_retina": "https://www.gravatar.com/avatar/9b006b129e4927a32c8784f962a7cac5?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/9b006b129e4927a32c8784f962a7cac5?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "small_retina": "https://www.gravatar.com/avatar/9b006b129e4927a32c8784f962a7cac5?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
      "small": "https://www.gravatar.com/avatar/9b006b129e4927a32c8784f962a7cac5?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
    },
    "type": "User",
    "work_days": "MON,TUE,WED,THU,FRI",
    "weekdays": "MO,TU,WE,TH,FR",
    "weekly_capacity": 40.0,
    "user_level": "admin",
    "admin": true,
    "hide_hourly_rate": false,
    "hide_internal_hourly_rate": true,
    "deleted": false,
    "default_hour_rate": 0.0,
    "internal_hour_rate": 0.0,
    "role_id": 1029,
    "role": {
      "id": 1029,
      "name": "admin"
    }
  }
]

Retrieve a user

Request

curl -g "https://api.timelyapp.com/1.1/256/users/555" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer x04I_9xKaf0t-D_6XhZf-zEGkaphw5IjS6Lulyz-SYA" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/:id

GET /1.1/256/users/555
Accept: application/json
Content-Type: application/json
Authorization: Bearer x04I_9xKaf0t-D_6XhZf-zEGkaphw5IjS6Lulyz-SYA

Parameters

Name Description
account_id The account ID containing the users you want to retrieve
id The ID of the user you want to retrieve

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 555,
  "email": "marijakajwdydc@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1741851969,
  "updated_at": 1741851969,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "memory_retention_days": null,
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/7406ee7d23bfda97c697dacc9b438d87?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/7406ee7d23bfda97c697dacc9b438d87?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/7406ee7d23bfda97c697dacc9b438d87?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/7406ee7d23bfda97c697dacc9b438d87?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/7406ee7d23bfda97c697dacc9b438d87?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/7406ee7d23bfda97c697dacc9b438d87?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
  },
  "type": "User",
  "work_days": "MON,TUE,WED,THU,FRI",
  "weekdays": "MO,TU,WE,TH,FR",
  "weekly_capacity": 40.0,
  "active_projects_count": 1,
  "user_level": "admin",
  "admin": true,
  "hide_hourly_rate": false,
  "hide_internal_hourly_rate": true,
  "deleted": false,
  "default_hour_rate": 0.0,
  "internal_hour_rate": 0.0,
  "role_id": 1021,
  "role": {
    "id": 1021,
    "name": "admin"
  }
}

Retrieve current user

Request

curl -g "https://api.timelyapp.com/1.1/257/users/current" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer tbmOYhAlx7kKFDqkslR134dtWw0g8HM0_aRowHRrSng" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/current

GET /1.1/257/users/current
Accept: application/json
Content-Type: application/json
Authorization: Bearer tbmOYhAlx7kKFDqkslR134dtWw0g8HM0_aRowHRrSng

Parameters

Name Description
account_id The account ID containing the current user

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 557,
  "email": "marijajaccojuq@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1741851969,
  "updated_at": 1741851969,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "memory_retention_days": null,
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/d0f1ea92a5b9e5bf6c639560b87555ff?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/d0f1ea92a5b9e5bf6c639560b87555ff?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/d0f1ea92a5b9e5bf6c639560b87555ff?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/d0f1ea92a5b9e5bf6c639560b87555ff?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/d0f1ea92a5b9e5bf6c639560b87555ff?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/d0f1ea92a5b9e5bf6c639560b87555ff?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
  },
  "type": "User",
  "work_days": "MON,TUE,WED,THU,FRI",
  "weekdays": "MO,TU,WE,TH,FR",
  "weekly_capacity": 40.0,
  "user_level": "admin",
  "admin": true,
  "hide_hourly_rate": false,
  "hide_internal_hourly_rate": true,
  "deleted": false,
  "default_hour_rate": 0.0,
  "internal_hour_rate": 0.0,
  "role_id": 1025,
  "role": {
    "id": 1025,
    "name": "admin"
  }
}

Update a user

Note:

Please use the parameters mentioned in “Create/Invite a user”.

Only admins can edit “user_level” and “projects” fields for other users.

Request

curl "https://api.timelyapp.com/1.1/259/users/561" -d '{"user":{"admin":{"id":220,"email":"notifications@timelyapp.com","created_at":"2025-03-13T07:46:09.000Z","updated_at":"2025-03-13T07:46:09.000Z","name":"Timely","notifier":true},"role_id":1033,"projects":[{"project_id":240,"hour_rate":10}]}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer eektKu55FqN-C8POT0UISO38pbScZsNd_twdUA_oPBQ" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/users/:id

PUT /1.1/259/users/561
Accept: application/json
Content-Type: application/json
Authorization: Bearer eektKu55FqN-C8POT0UISO38pbScZsNd_twdUA_oPBQ

Parameters

{"user":{"admin":{"id":220,"email":"notifications@timelyapp.com","created_at":"2025-03-13T07:46:09.000Z","updated_at":"2025-03-13T07:46:09.000Z","name":"Timely","notifier":true},"role_id":1033,"projects":[{"project_id":240,"hour_rate":10}]}}
Name Description
id required The numerical ID of the user
user required Label attributes
user[projects] Specifies the projects that the user will be part of. For example: "projects": [ {"project_id": 11 , "hour_rate": 10 }, {"project_id": 12 , "hour_rate": 20 }]
user[role_id] required Specifies the user's role in the account
user[user_level] (Deprecated) Specifies the user level; either “normal” or “limited”. The default is "normal". For example: "user_level": "normal"
user[admin] (Deprecated) Specifies the user is an admin. In this case user_level should be “normal”. For example: "admin": "true"
user[weekly_capacity] Specifies the user's weekly hour capacity. The default is the account's weekly capacity. To avoid rounding issues, values are allowed upto 1 decimal place and divisible by 5.
user[add_to_all_projects] Specifies whether the user should be added to all projects in the account. For example: "add_to_all_projects":true
user[internal_hour_rate] Specifies the internal hourly rate for users in the account
user[hide_internal_hourly_rate] The hide_internal_hourly_rate hides the internal hourly rate for users in the account. The default is true. For example: "hide_internal_hourly_rate": true
update_existing_hours Specifies if the updated hour rate should be applied to existing hours. For example: "update_existing_hours":false. Default: true
update_unbilled_only Specifies if the updated hour rate should only be applied to unbilled hours. This is ignored if "update_existing_hours" is false. For example: "update_unbilled_only":true. Default: false
update_existing_hours_internal_rate Specifies if the updated internal hour rate should be applied to existing hours. For example: "update_existing_hours_internal_rate":false. Default: true
update_unbilled_hours_internal_rate Specifies if the updated internal hour rate should only be applied to unbilled hours. This is ignored if "update_existing_hours_internal_rate" is false. For example: "update_unbilled_hours_internal_rate":true. Default: false
team_ids Specifies the teams that the user will be part of, should be array of numerical team id's. Example values: team_ids: [3,4,2]
add_team_users_to_projects Specifies if the user should be added to team projects Specified in team_ids. For example: "add_team_users_to_projects":false. Default: true
remove_team_users_from_projects Specifies if the user should be removed from team projects not specified in team_ids. For example: "remove_team_users_from_projects":true. Default: false

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 561,
  "email": "marijahltusifw@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1741851969,
  "updated_at": 1741851969,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "memory_retention_days": null,
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/12058cd92094d5f194bf7e03a7a95d0a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/12058cd92094d5f194bf7e03a7a95d0a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/12058cd92094d5f194bf7e03a7a95d0a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/12058cd92094d5f194bf7e03a7a95d0a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/12058cd92094d5f194bf7e03a7a95d0a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/12058cd92094d5f194bf7e03a7a95d0a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
  },
  "type": "User",
  "work_days": "MON,TUE,WED,THU,FRI",
  "weekdays": "MO,TU,WE,TH,FR",
  "weekly_capacity": 40.0,
  "user_level": "admin",
  "admin": true,
  "hide_hourly_rate": false,
  "hide_internal_hourly_rate": false,
  "deleted": false,
  "default_hour_rate": 0.0,
  "internal_hour_rate": 0.0,
  "role_id": 1033,
  "role": {
    "id": 1033,
    "name": "admin"
  }
}

Webhooks

Webhooks allow external services to be notified when certain events happen. When the specified events happen, we’ll send a POST request to each of the URLs you provide.

Create a webhook

Request

curl "https://api.timelyapp.com/1.1/264/webhooks" -d '{"webhook":{"url":"https://boehm-marvin.co/renaldo.padberg","subscriptions":["projects:created"],"active":true,"secret_token":"deadbeef"}}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer nQYOA2temS13FMpvj5aeJpRkhLekufBfckSSvhctxRw" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/webhooks

POST /1.1/264/webhooks
Accept: application/json
Content-Type: application/json
Authorization: Bearer nQYOA2temS13FMpvj5aeJpRkhLekufBfckSSvhctxRw

Parameters

{"webhook":{"url":"https://boehm-marvin.co/renaldo.padberg","subscriptions":["projects:created"],"active":true,"secret_token":"deadbeef"}}
Name Description
url required The URL of the endpoint that will receive the webhook POST requests. (HTTPS required)
secret_token Setting a webhook secret allows you to ensure that requests sent to the above webhook endpoint are from us. You'll receive a signature in the X-Signature header value. Calculate a SHA256 hash for the received payload using your provided SECRET_TOKEN on your end, and ensure that the result matches the X-Signature value.
subscriptions Specifies the array of events should it listen to. The format is ['entity:action', ...]. Eg. ['project:created']. Use the wildcard (*) character for all events or all actions of an entity.
Support subscriptions:
  • forecasts:created
  • forecasts:updated
  • forecasts:deleted
  • hours:created
  • hours:updated
  • hours:deleted
  • labels:created
  • labels:updated
  • labels:deleted
  • projects:created
  • projects:updated
  • projects:deleted
active By default, webhook deliveries are active. You can choose to disable the delivery of webhook payloads by disable this.

Response

Content-Type: application/json; charset=utf-8
201 Created

{
  "id": 1,
  "account_id": 264,
  "url": "https://boehm-marvin.co/renaldo.padberg",
  "subscriptions": [
    "projects:created"
  ],
  "secret_token": "deadbeef",
  "active": true,
  "created_at": "2025-03-13T08:46:10+01:00",
  "updated_at": "2025-03-13T08:46:10+01:00"
}

Delete a webhook

Request

curl "https://api.timelyapp.com/1.1/265/webhooks/2" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer dDlJEn5uBH8ufzjYFBV3SjEsokwJ99b22dy7XOXcyxI" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/webhooks/:id

DELETE /1.1/265/webhooks/2
Accept: application/json
Content-Type: application/json
Authorization: Bearer dDlJEn5uBH8ufzjYFBV3SjEsokwJ99b22dy7XOXcyxI

Parameters

Name Description
account_id The account ID containing the webhook you want to delete
id The ID of the webhook you want to delete

Response

Content-Type: application/json; charset=utf-8
200 OK

{}

List all webhooks

Request

curl -g "https://api.timelyapp.com/1.1/267/webhooks" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Whh6AjbO2IGR3CEw-HkZHfW-xThCm8ppQ-tk1RYwEH0" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/webhooks

GET /1.1/267/webhooks
Accept: application/json
Content-Type: application/json
Authorization: Bearer Whh6AjbO2IGR3CEw-HkZHfW-xThCm8ppQ-tk1RYwEH0

Parameters

Name Description
account_id The account ID containing the webhooks you want to retrieve
offset Retrieve webhooks from offset
limit Retrieve number of webhooks

Response

Content-Type: application/json; charset=utf-8
200 OK

[]

Retrieve a webhook

Request

curl -g "https://api.timelyapp.com/1.1/266/webhooks/3" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer q2IHZAUjizzTfXo1VcHfJxULeMNskOICcXypcdUzTWo" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/webhooks/:id

GET /1.1/266/webhooks/3
Accept: application/json
Content-Type: application/json
Authorization: Bearer q2IHZAUjizzTfXo1VcHfJxULeMNskOICcXypcdUzTWo

Parameters

Name Description
account_id The account ID containing the webhook you want to retrieve
id The ID of the webhook you want to retrieve

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 3,
  "account_id": 266,
  "url": "https://jenkins.biz/camille.kunze",
  "subscriptions": [
    "projects:created"
  ],
  "secret_token": null,
  "active": true,
  "created_at": "2025-03-13T08:46:11+01:00",
  "updated_at": "2025-03-13T08:46:11+01:00"
}

Update a webhook

Request

curl "https://api.timelyapp.com/1.1/268/webhooks/4" -d '{"webhook":{"subscriptions":["projects:created","labels:created"],"secret_token":"deadbeef"}}' -X PUT \
    -H "Version: HTTP/1.0" \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer OAftO6yXepBtKPvgzq9CMNdKiAg-KiMka3yB45SS1mg" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/webhooks/:id

PUT /1.1/268/webhooks/4
Accept: application/json
Content-Type: application/json
Authorization: Bearer OAftO6yXepBtKPvgzq9CMNdKiAg-KiMka3yB45SS1mg

Parameters

{"webhook":{"subscriptions":["projects:created","labels:created"],"secret_token":"deadbeef"}}
Name Description
id required Webhook ID
url required The URL of the endpoint that will receive the webhook POST requests. (HTTPS required)
secret_token Setting a webhook secret allows you to ensure that requests sent to the above webhook endpoint are from us. You'll receive a signature in the X-Signature header value. Calculate a SHA256 hash for the received payload using your provided SECRET_TOKEN on your end, and ensure that the result matches the X-Signature value.
subscriptions Specifies the array of events should it listen to. The format is ['entity:action', ...]. Eg. ['projects:created']. Use the wildcard (*) character for all events or all actions of an entity.
active Example values: "true" or "false"

Response

Content-Type: application/json; charset=utf-8
200 OK

{
  "id": 4,
  "account_id": 268,
  "url": "https://greenholt.name/charlotte.treutel",
  "subscriptions": [
    "projects:created",
    "labels:created"
  ],
  "secret_token": "deadbeef",
  "active": true,
  "created_at": "2025-03-13T08:46:11+01:00",
  "updated_at": "2025-03-13T08:46:11+01:00"
}

Errors

Example responses:

422 Unprocessable Entity

{
  "errors":{
    "name":[
      "can't be blank"
    ],
    "project_users":[
      "is invalid"
    ]
  }
}

422 Unprocessable Entity

403 Forbidden

{
  "errors":{
    "message":"error message"
  }
}

404 Not Found

{
  "errors":{
    "message":"Not Found"
  }
}

401 Unauthorized

{
  "errors":{
    "message":"Unauthorized"
  }
}

Timely uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed due to the information provided. Codes in the 5xx range indicate an error with Timely's servers.

Unauthorized access o projects and accounts, or trying to create or delete objects that are not under our control, will result in errors.

The Timely API uses the following error codes:

Error Code Meaning
400 - Bad Request Your request is invalid
401 - Unauthorized Wrong authentication token was used
403 - Forbidden The entity requested is hidden from unauthorized access
404 - Not Found The specified entity could not be found
422 - Unprocessable Entity The server understands the content type, but was unable to process the request
500 - Internal Server Error We’re experiencing a problem with our server. Try again later.
cURL