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 "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YhxBOXxck-V2GlLIimzVlZMeTlCdR3Jzqtb0yVjLekU" \
    -H "Cookie: "

Endpoint

GET /1.1/accounts

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

Parameters

None known.

Response

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

[
  {
    "id": 2034,
    "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": 2046,
    "plan_name": "Essential",
    "next_charge": "2022-01-28",
    "start_of_week": 0,
    "created_at": 1640695666,
    "payment_mode": "web",
    "paid": true,
    "company_size": "10-49",
    "plan_code": "essential",
    "plan_custom": false,
    "appstore_transaction_id": null,
    "owner_id": 5032,
    "weekly_user_capacity": 40.0,
    "default_hour_rate": 0.0,
    "support_email": "support@timelyapp.com",
    "estimated_company_size": null,
    "industry": null,
    "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,
    "expired": false,
    "trial": false,
    "days_to_end_trial": 0,
    "features": [
      {
        "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": "tasks",
        "days": -1
      },
      {
        "name": "planning",
        "days": -1
      },
      {
        "name": "batch_log_planned_time",
        "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/2032/activities" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer KBRknqhPizDujkgsmg95PkgJw1mBfnu6uL1l0Pt9SU8" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/activities

GET /1.1/2032/activities
Accept: application/json
Content-Type: application/json
Authorization: Bearer KBRknqhPizDujkgsmg95PkgJw1mBfnu6uL1l0Pt9SU8

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": 206,
    "user": {
      "id": 5027,
      "email": "marijaqoifbheh@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2021-12-28T13:47:45+01:00"
    },
    "message": "archived",
    "activity_type": "archive_project",
    "url": "http://app.timelyapp.local:3002/2032/projects/2027",
    "updated_at": "2021-12-21T13:47:45+01:00",
    "detail": null,
    "associated_ids": [],
    "entity_type": "Project",
    "entity_deleted": false,
    "parent_entity_name": "",
    "entity": {
      "id": 2027,
      "active": true,
      "name": "Timely",
      "color": "67a3bc",
      "client": {
        "id": 1463,
        "name": "Exercitationem velit occaecati ut.",
        "active": true,
        "external_id": null,
        "updated_at": "2021-12-28T13:47:45+01:00"
      },
      "updated_at": "2021-12-28T13:47:45+01:00"
    },
    "anomaly": false
  },
  {
    "id": 205,
    "user": {
      "id": 5027,
      "email": "marijaqoifbheh@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/c0548dc1598427c8b75c476bcacb504d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2021-12-28T13:47:45+01:00"
    },
    "message": "50% of budget used",
    "activity_type": "project_budget_progress_fifty",
    "url": "http://app.timelyapp.local:3002/2032/projects/2027",
    "updated_at": "2021-12-28T13:47:45+01:00",
    "detail": null,
    "associated_ids": [],
    "entity_type": "Project",
    "entity_deleted": false,
    "parent_entity_name": "",
    "entity": {
      "id": 2027,
      "active": true,
      "name": "Timely",
      "color": "67a3bc",
      "client": {
        "id": 1463,
        "name": "Exercitationem velit occaecati ut.",
        "active": true,
        "external_id": null,
        "updated_at": "2021-12-28T13:47:45+01:00"
      },
      "updated_at": "2021-12-28T13:47:45+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/2033" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer D06f8fsvM_AryNG_9DD6fSPr9EidmRbypoDDsDUUp7U" \
    -H "Cookie: "

Endpoint

GET /1.1/accounts/:id

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

Parameters

Name	Description
id	The id of the account to be retrieved

Response

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

{
  "id": 2033,
  "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": 2045,
  "plan_name": "Essential",
  "next_charge": "2022-01-28",
  "start_of_week": 0,
  "created_at": 1640695665,
  "payment_mode": "web",
  "paid": true,
  "company_size": "10-49",
  "plan_code": "essential",
  "plan_custom": false,
  "appstore_transaction_id": null,
  "owner_id": 5030,
  "weekly_user_capacity": 40.0,
  "default_hour_rate": 0.0,
  "support_email": "support@timelyapp.com",
  "estimated_company_size": null,
  "industry": null,
  "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,
  "expired": false,
  "trial": false,
  "days_to_end_trial": 0,
  "features": [
    {
      "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": "tasks",
      "days": -1
    },
    {
      "name": "planning",
      "days": -1
    },
    {
      "name": "batch_log_planned_time",
      "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/2052/clients" -d '{"name":null,"client":{"name":"Uniq name","active":true,"external_id":null}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 3JWOB0ezGI8GhKOsuNUgkGvcnlps9XykT5CFwjtlOtY" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/clients

POST /1.1/2052/clients
Accept: application/json
Content-Type: application/json
Authorization: Bearer 3JWOB0ezGI8GhKOsuNUgkGvcnlps9XykT5CFwjtlOtY

Parameters

{"name":null,"client":{"name":"Uniq name","active":true,"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)

Response

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

{
  "id": 1479,
  "name": "Uniq name",
  "active": true,
  "external_id": null,
  "updated_at": "2021-12-28T13:47:49+01:00"
}

List all clients

NOTE: Client list will return recently updated 10000 clients. Additionally, you can add the “limit”, “offset”, “filter” and “order” optional parameters to change the result.

Request

curl -g "https://api.timelyapp.com/1.1/2053/clients" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ZSPMynG2F_L5h_AZeUlLuKKcXzWG7CIAGq45nY3-Pvk" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/clients

GET /1.1/2053/clients
Accept: application/json
Content-Type: application/json
Authorization: Bearer ZSPMynG2F_L5h_AZeUlLuKKcXzWG7CIAGq45nY3-Pvk

Parameters

Name	Description
account_id	Account ID for the clients you want to retrieve
offset	Retrieve clients from offset
limit	Retrieve number of clients
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": 1480,
    "name": "Eius repellendus voluptates assumenda.",
    "active": true,
    "external_id": null,
    "updated_at": "2021-12-28T13:47:49+01:00",
    "external_references": []
  }
]

Show client

Request

curl -g "https://api.timelyapp.com/1.1/2055/clients/1482" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fJnkJ3BTzuYXJH_OQpI7DqDigoQQ9S2llE_VVZip_PI" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/clients/:id

GET /1.1/2055/clients/1482
Accept: application/json
Content-Type: application/json
Authorization: Bearer fJnkJ3BTzuYXJH_OQpI7DqDigoQQ9S2llE_VVZip_PI

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": 1482,
  "name": "Perspiciatis rerum cupiditate tempore.",
  "active": true,
  "external_id": null,
  "updated_at": "2021-12-28T13:47:49+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/2057/clients/1484" -d '{"name":null,"client":{"name":"Updated name","active":true}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer KZTSsfFBVH6rRy6KEgG4T1doZnnzx6UDSMB3eEHu9K0" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/clients/:id

PUT /1.1/2057/clients/1484
Accept: application/json
Content-Type: application/json
Authorization: Bearer KZTSsfFBVH6rRy6KEgG4T1doZnnzx6UDSMB3eEHu9K0

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)

Response

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

{
  "id": 1484,
  "name": "Updated name",
  "active": true,
  "external_id": null,
  "updated_at": "2021-12-28T13:47:50+01:00"
}

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/2076/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2021-12-28T13:47:52.152+01:00","to":"2021-12-28T17:17:52.152+01:00","day":"2021-12-28","note":"Notes for testing with some random #hash in it.","hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":2054}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer y8JVbHuDs3QywS7bnO5ew3QQUljYb8A0i8RFivrURsU" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/events

POST /1.1/2076/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer y8JVbHuDs3QywS7bnO5ew3QQUljYb8A0i8RFivrURsU

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2021-12-28T13:47:52.152+01:00","to":"2021-12-28T17:17:52.152+01:00","day":"2021-12-28","note":"Notes for testing with some random #hash in it.","hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":2054}}

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": 3472,
  "uid": "2974788b53f73e7950e8aa49f3a306db",
  "user": {
    "id": 5121,
    "email": "marijaoynfppca@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/6ffbff2e9118e1c444c85995e3706325?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/6ffbff2e9118e1c444c85995e3706325?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/6ffbff2e9118e1c444c85995e3706325?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/6ffbff2e9118e1c444c85995e3706325?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/6ffbff2e9118e1c444c85995e3706325?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:51+01:00"
  },
  "project": {
    "id": 2054,
    "active": true,
    "account_id": 2076,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695672,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1491,
      "name": "Est et officiis consequatur.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:52+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0
  },
  "day": "2021-12-28",
  "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": 1640695672,
  "created_at": 1640695672,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:52+01:00",
  "from": "2021-12-28T13:47:52+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": 5121,
  "updater_id": 5121,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

Create an event for a project

Request

curl "https://api.timelyapp.com/1.1/2075/projects/2053/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2021-12-28T13:47:51.933+01:00","to":"2021-12-28T17:17:51.933+01:00","day":"2021-12-28","note":"Notes for testing with some random #hash in it.","hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":2053}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 8N95gb1hvN_2axZSZb_wloafHk-LSGoP83AwHm-uOpU" \
    -H "Cookie: "

Endpoint

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

POST /1.1/2075/projects/2053/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer 8N95gb1hvN_2axZSZb_wloafHk-LSGoP83AwHm-uOpU

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2021-12-28T13:47:51.933+01:00","to":"2021-12-28T17:17:51.933+01:00","day":"2021-12-28","note":"Notes for testing with some random #hash in it.","hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":2053}}

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": 3471,
  "uid": "735143e9ff8c47def504f1ba0442df98",
  "user": {
    "id": 5119,
    "email": "marijatalmjbzo@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/3f62764eaf1781d00b9311c6f5404212?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/3f62764eaf1781d00b9311c6f5404212?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/3f62764eaf1781d00b9311c6f5404212?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/3f62764eaf1781d00b9311c6f5404212?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/3f62764eaf1781d00b9311c6f5404212?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:51+01:00"
  },
  "project": {
    "id": 2053,
    "active": true,
    "account_id": 2075,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695671,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1490,
      "name": "Et ad aliquid expedita.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:51+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0
  },
  "day": "2021-12-28",
  "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": 1640695671,
  "created_at": 1640695671,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:51+01:00",
  "from": "2021-12-28T13:47:51+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": 5119,
  "updater_id": 5119,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

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/2074/users/5117/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2021-12-28T13:47:51.697+01:00","to":"2021-12-28T17:17:51.697+01:00","day":"2021-12-28","note":"Notes for testing with some random #hash in it.","hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":5117}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Fq-aEvb02Z__EgIKSh-NCiwQzpdsPJxe4iKxCrujjJw" \
    -H "Cookie: "

Endpoint

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

POST /1.1/2074/users/5117/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer Fq-aEvb02Z__EgIKSh-NCiwQzpdsPJxe4iKxCrujjJw

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2021-12-28T13:47:51.697+01:00","to":"2021-12-28T17:17:51.697+01:00","day":"2021-12-28","note":"Notes for testing with some random #hash in it.","hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":5117}}

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": 3470,
  "uid": "73fed7fd472e502d8908794430511f4d",
  "user": {
    "id": 5117,
    "email": "marijaxgwbfudj@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/ace7526c366724900228530217acc825?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/ace7526c366724900228530217acc825?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/ace7526c366724900228530217acc825?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/ace7526c366724900228530217acc825?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/ace7526c366724900228530217acc825?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:51+01:00"
  },
  "project": {
    "id": 2052,
    "active": true,
    "account_id": 2074,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695671,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1489,
      "name": "Impedit nulla est quia.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:51+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0
  },
  "day": "2021-12-28",
  "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": 1640695671,
  "created_at": 1640695671,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:51+01:00",
  "from": "2021-12-28T13:47:51+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": 5117,
  "updater_id": 5117,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

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/2073/bulk/events" -d '{"create":[{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2021-12-28T13:47:51.463+01:00","to":"2021-12-28T17:17:51.464+01:00","day":"2021-12-28","note":"Notes for testing with some random #hash in it.","hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":5115,"account_id":2073,"project_id":2051}]}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ea6m9mGSeNl-7AoFkyz4AmW-6NYWEomT16CkaFscjS8" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/bulk/events

POST /1.1/2073/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer ea6m9mGSeNl-7AoFkyz4AmW-6NYWEomT16CkaFscjS8

Parameters

{"create":[{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2021-12-28T13:47:51.463+01:00","to":"2021-12-28T17:17:51.464+01:00","day":"2021-12-28","note":"Notes for testing with some random #hash in it.","hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":5115,"account_id":2073,"project_id":2051}]}

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": [
    3469
  ],
  "updated_ids": [],
  "errors": {
    "create": [],
    "update": []
  }
}

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/2078/events/3474" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer nRyE7j8yVVZy1Ca1HLsnPey8f44bVE0s1UezaDwGWzs" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/events/:id

DELETE /1.1/2078/events/3474
Accept: application/json
Content-Type: application/json
Authorization: Bearer nRyE7j8yVVZy1Ca1HLsnPey8f44bVE0s1UezaDwGWzs

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/2077/bulk/events" -d '{"delete":[3473]}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer oSNjSEDQ5EpKFlJW5V62VkXhRLQmwzdTZI6KJvToqH4" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/bulk/events

POST /1.1/2077/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer oSNjSEDQ5EpKFlJW5V62VkXhRLQmwzdTZI6KJvToqH4

Parameters

{"delete":[3473]}

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": [
    3473
  ],
  "created_ids": [],
  "updated_ids": [],
  "errors": {
    "create": [],
    "update": []
  }
}

List all events

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

Note: If “since” and “upto” parameters are not passed, the period will default to the date of access.

Request

curl -g "https://api.timelyapp.com/1.1/2083/events" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer C5fR1QcSZPW_N9DTWXlnCNU1XL2O7OfrAe_HFDewCPY" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/events

GET /1.1/2083/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer C5fR1QcSZPW_N9DTWXlnCNU1XL2O7OfrAe_HFDewCPY

Parameters

Name	Description
account_id	The account ID containing the hours you want to retrieve
day	Specifies the day date for returned results. 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 records to retrieve (Default logged). Example: filter=logged or filter=all
sort	Field to sort projects by (Default updated_at)
order	Order to retrieve records (Default updated_at DESC)
per_page	Records per page (Default 100)
page	Page number (Default 1)

Response

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

[
  {
    "id": 3479,
    "uid": "6950aa02ae8613af620668146dd11840",
    "user": {
      "id": 5135,
      "email": "marijanrmjvbzo@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/66b647a27b08be15ccbb56bba76bc159?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/66b647a27b08be15ccbb56bba76bc159?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/66b647a27b08be15ccbb56bba76bc159?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/66b647a27b08be15ccbb56bba76bc159?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/66b647a27b08be15ccbb56bba76bc159?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2021-12-28T13:47:53+01:00"
    },
    "project": {
      "id": 2061,
      "active": true,
      "account_id": 2083,
      "name": "Timely",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "updated_at": 1640695673,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 1498,
        "name": "Aut sunt et ut.",
        "active": true,
        "external_id": null,
        "updated_at": "2021-12-28T13:47:53+01:00"
      },
      "required_notes": false,
      "required_labels": false,
      "budget_expired_on": null,
      "has_recurrence": false,
      "enable_labels": "all",
      "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": []
    },
    "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
    },
    "estimated_cost": {
      "fractional": 40000,
      "formatted": "$400.00",
      "amount": 400.0
    },
    "day": "2021-12-28",
    "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": 1640695673,
    "created_at": 1640695673,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "billable": true,
    "to": "2021-12-28T17:17:53+01:00",
    "from": "2021-12-28T13:47:53+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,
    "locked_reason": null,
    "locked": false,
    "invoice_id": null,
    "timestamps": []
  }
]

List all events for a project

Note: Normal users can access events logged to all projects on an account. Limited users can only access events in projects they belong to.

Request

curl -g "https://api.timelyapp.com/1.1/2086/projects/2064/events" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer RRX8J1MprvEEbBKwbT9gLX3b7zHvNaAM8k8sMJDIyJY" \
    -H "Cookie: "

Endpoint

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

GET /1.1/2086/projects/2064/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer RRX8J1MprvEEbBKwbT9gLX3b7zHvNaAM8k8sMJDIyJY

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
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
day	Specifies the day date for returned results. Example: day=2014-08-24
sort	Field to sort projects by (Default updated_at)
order	Order to retrieve records (Default updated_at DESC)
per_page	Records per page (Default 100)
page	Page number (Default 1)

Response

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

[
  {
    "id": 3482,
    "uid": "b7fede84c2be02ccb9c77107956560eb",
    "user": {
      "id": 5141,
      "email": "marijafdjizxcd@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/c8ec8ff3aa9d7e637ef4a85dc39889e4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/c8ec8ff3aa9d7e637ef4a85dc39889e4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/c8ec8ff3aa9d7e637ef4a85dc39889e4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/c8ec8ff3aa9d7e637ef4a85dc39889e4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/c8ec8ff3aa9d7e637ef4a85dc39889e4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2021-12-28T13:47:54+01:00"
    },
    "project": {
      "id": 2064,
      "active": true,
      "account_id": 2086,
      "name": "Timely",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "updated_at": 1640695674,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 1501,
        "name": "Sequi ut tenetur voluptatibus.",
        "active": true,
        "external_id": null,
        "updated_at": "2021-12-28T13:47:54+01:00"
      },
      "required_notes": false,
      "required_labels": false,
      "budget_expired_on": null,
      "has_recurrence": false,
      "enable_labels": "all",
      "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": []
    },
    "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
    },
    "estimated_cost": {
      "fractional": 40000,
      "formatted": "$400.00",
      "amount": 400.0
    },
    "day": "2021-12-28",
    "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": 1640695674,
    "created_at": 1640695674,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "billable": true,
    "to": "2021-12-28T17:17:54+01:00",
    "from": "2021-12-28T13:47:54+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,
    "locked_reason": null,
    "locked": false,
    "invoice_id": null,
    "timestamps": []
  }
]

List all events for a user

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

Request

curl -g "https://api.timelyapp.com/1.1/2085/users/5139/events" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer zFvirmDvsLoEtjTacgo_Wca9fRuV6vAHOtTeNk-QEpk" \
    -H "Cookie: "

Endpoint

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

GET /1.1/2085/users/5139/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer zFvirmDvsLoEtjTacgo_Wca9fRuV6vAHOtTeNk-QEpk

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
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
day	Specifies the day date for returned results. Example: day=2014-08-24
sort	Field to sort projects by (Default updated_at)
order	Order to retrieve records (Default updated_at DESC)
per_page	Records per page (Default 100)
page	Page number (Default 1)

Response

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

[
  {
    "id": 3481,
    "uid": "3fb04953d95a94367bb133f862402bce",
    "user": {
      "id": 5139,
      "email": "marijajgkckvfw@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/637e40d9240f85ece4b5a77907068898?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/637e40d9240f85ece4b5a77907068898?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/637e40d9240f85ece4b5a77907068898?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/637e40d9240f85ece4b5a77907068898?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/637e40d9240f85ece4b5a77907068898?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
      },
      "updated_at": "2021-12-28T13:47:53+01:00"
    },
    "project": {
      "id": 2063,
      "active": true,
      "account_id": 2085,
      "name": "Timely",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "updated_at": 1640695674,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 1500,
        "name": "Ratione nihil voluptate facere.",
        "active": true,
        "external_id": null,
        "updated_at": "2021-12-28T13:47:54+01:00"
      },
      "required_notes": false,
      "required_labels": false,
      "budget_expired_on": null,
      "has_recurrence": false,
      "enable_labels": "all",
      "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": []
    },
    "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
    },
    "estimated_cost": {
      "fractional": 40000,
      "formatted": "$400.00",
      "amount": 400.0
    },
    "day": "2021-12-28",
    "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": 1640695674,
    "created_at": 1640695674,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "billable": true,
    "to": "2021-12-28T17:17:54+01:00",
    "from": "2021-12-28T13:47:54+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,
    "locked_reason": null,
    "locked": false,
    "invoice_id": null,
    "timestamps": []
  }
]

Logged in user updating details and user of an event

Request

curl "https://api.timelyapp.com/1.1/2093/users/5155/events/3489" -d '{"event":{"note":"Updated details and project","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer yw8bQ0ieh0Y8wN-tAWH17Q1WzBN3RZCwQfsWfW-Qm6k" \
    -H "Cookie: "

Endpoint

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

PUT /1.1/2093/users/5155/events/3489
Accept: application/json
Content-Type: application/json
Authorization: Bearer yw8bQ0ieh0Y8wN-tAWH17Q1WzBN3RZCwQfsWfW-Qm6k

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": 3489,
  "uid": "1b318124e37af6d74a03501474f44ea1",
  "user": {
    "id": 5155,
    "email": "marijadsrepevs@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/1b8c35d27d24137fbd841af64601d4f6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/1b8c35d27d24137fbd841af64601d4f6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/1b8c35d27d24137fbd841af64601d4f6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/1b8c35d27d24137fbd841af64601d4f6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/1b8c35d27d24137fbd841af64601d4f6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:55+01:00"
  },
  "project": {
    "id": 2071,
    "active": true,
    "account_id": 2093,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695675,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1508,
      "name": "Enim quos fuga voluptatem.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:55+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2021-12-28",
  "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": 1640695675,
  "created_at": 1640695675,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:55+01:00",
  "from": "2021-12-28T13:47:55+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 5155,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

Loggedin user updating details and project of their event

Request

curl "https://api.timelyapp.com/1.1/2092/projects/2070/events/3488" -d '{"event":{"note":"Updated details and project","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WiN1SOK8H3H-JvubU8YxdB8lreC9Y5sMRYNLZG-Ersc" \
    -H "Cookie: "

Endpoint

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

PUT /1.1/2092/projects/2070/events/3488
Accept: application/json
Content-Type: application/json
Authorization: Bearer WiN1SOK8H3H-JvubU8YxdB8lreC9Y5sMRYNLZG-Ersc

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": 3488,
  "uid": "c7b90b0fc23725f299b47c5224e6ec0d",
  "user": {
    "id": 5153,
    "email": "marijaijdcmdyr@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/0cbcf4cdf399b732c388efa73d1d7479?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/0cbcf4cdf399b732c388efa73d1d7479?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/0cbcf4cdf399b732c388efa73d1d7479?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/0cbcf4cdf399b732c388efa73d1d7479?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/0cbcf4cdf399b732c388efa73d1d7479?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:55+01:00"
  },
  "project": {
    "id": 2070,
    "active": true,
    "account_id": 2092,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695675,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1507,
      "name": "Velit provident optio reprehenderit.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:55+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2021-12-28",
  "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": 1640695675,
  "created_at": 1640695675,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:55+01:00",
  "from": "2021-12-28T13:47:55+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 5153,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

Retrieve an event

Request

curl -g "https://api.timelyapp.com/1.1/2081/events/3477" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer W17UvtHkZE1M0Zg_b2vTz3Org8ZiqDGK9zTggTwO_gs" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/events/:id

GET /1.1/2081/events/3477
Accept: application/json
Content-Type: application/json
Authorization: Bearer W17UvtHkZE1M0Zg_b2vTz3Org8ZiqDGK9zTggTwO_gs

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": 3477,
  "uid": "6d6968d87c240c699190e2d8c029fa9d",
  "user": {
    "id": 5131,
    "email": "marijaioehyndr@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/7814806226a342dcfdf12561e5a91fd6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/7814806226a342dcfdf12561e5a91fd6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/7814806226a342dcfdf12561e5a91fd6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/7814806226a342dcfdf12561e5a91fd6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/7814806226a342dcfdf12561e5a91fd6?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:53+01:00"
  },
  "project": {
    "id": 2059,
    "active": true,
    "account_id": 2081,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695673,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1496,
      "name": "Perspiciatis magni qui voluptatum.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:53+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0
  },
  "day": "2021-12-28",
  "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": 1640695673,
  "created_at": 1640695673,
  "created_from": "Web",
  "updated_from": "Web",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:53+01:00",
  "from": "2021-12-28T13:47:53+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,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

Start timer on an event

Request

curl "https://api.timelyapp.com/1.1/2087/events/3483/start" -d '' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer _rr-HUTjH62HW80atCVZrRoaFhfDL8UDJPx2XMsaAdU" \
    -H "Cookie: "

Endpoint

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

PUT /1.1/2087/events/3483/start
Accept: application/json
Content-Type: application/json
Authorization: Bearer _rr-HUTjH62HW80atCVZrRoaFhfDL8UDJPx2XMsaAdU

Parameters

Name	Description
id required	Event ID

Response

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

{
  "id": 3483,
  "uid": "cb953f6ca5923f7517125db46ed1293d",
  "user": {
    "id": 5143,
    "email": "marijaqgdtnegf@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/a388c4616c065d167cc6b424f19a9e52?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/a388c4616c065d167cc6b424f19a9e52?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/a388c4616c065d167cc6b424f19a9e52?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/a388c4616c065d167cc6b424f19a9e52?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/a388c4616c065d167cc6b424f19a9e52?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:54+01:00"
  },
  "project": {
    "id": 2065,
    "active": true,
    "account_id": 2087,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695674,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1502,
      "name": "Aut enim nemo omnis.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:54+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0
  },
  "day": "2021-12-28",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "start",
  "timer_started_on": 1640695674,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1640695674,
  "created_at": 1640695674,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:54+01:00",
  "from": "2021-12-28T13:47:54+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 5143,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

Stop timer on an event

Request

curl "https://api.timelyapp.com/1.1/2088/events/3484/stop" -d '' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 1xSoibCE5d2cPnlb0Dg3PNZa8-zPs8NH5nWvdmxDpoQ" \
    -H "Cookie: "

Endpoint

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

PUT /1.1/2088/events/3484/stop
Accept: application/json
Content-Type: application/json
Authorization: Bearer 1xSoibCE5d2cPnlb0Dg3PNZa8-zPs8NH5nWvdmxDpoQ

Parameters

Name	Description
id required	Event ID

Response

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

{
  "id": 3484,
  "uid": "966b6dfb6b0819cc10644bea3115cf20",
  "user": {
    "id": 5145,
    "email": "marijabjrhnfyb@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/831545faf9d90b3a3bd5a2495e17af8e?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/831545faf9d90b3a3bd5a2495e17af8e?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/831545faf9d90b3a3bd5a2495e17af8e?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/831545faf9d90b3a3bd5a2495e17af8e?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/831545faf9d90b3a3bd5a2495e17af8e?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:54+01:00"
  },
  "project": {
    "id": 2066,
    "active": true,
    "account_id": 2088,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695674,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1503,
      "name": "Explicabo quae dolorem aut.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:54+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 40000,
    "formatted": "$400.00",
    "amount": 400.0
  },
  "day": "2021-12-28",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "stop",
  "timer_started_on": 0,
  "timer_stopped_on": 1640695674,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1640695674,
  "created_at": 1640695674,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:54+01:00",
  "from": "2021-12-28T13:47:54+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 5145,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

Update an event

Request

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

Endpoint

PUT /1.1/:account_id/events/:id

PUT /1.1/2091/events/3487
Accept: application/json
Content-Type: application/json
Authorization: Bearer uumkxYrXCs0qs63BHrgcJIZbRpQ058Rks3llsFRwP9Q

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": 3487,
  "uid": "944a5ae3483ed5c1e10bbccb7942a279",
  "user": {
    "id": 5151,
    "email": "marijaebrbhjfc@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/dcef8b053ccd7889d9551f3683c4a245?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/dcef8b053ccd7889d9551f3683c4a245?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/dcef8b053ccd7889d9551f3683c4a245?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/dcef8b053ccd7889d9551f3683c4a245?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
      "timeline": "https://www.gravatar.com/avatar/dcef8b053ccd7889d9551f3683c4a245?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
    },
    "updated_at": "2021-12-28T13:47:55+01:00"
  },
  "project": {
    "id": 2069,
    "active": true,
    "account_id": 2091,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695675,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1506,
      "name": "Odio assumenda eos reiciendis.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:47:55+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": []
  },
  "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
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2021-12-28",
  "note": "Updated notes",
  "sequence": 1,
  "estimated": true,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [],
  "user_ids": [],
  "updated_at": 1640695675,
  "created_at": 1640695675,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "billable": true,
  "to": "2021-12-28T17:17:55+01:00",
  "from": "2021-12-28T13:47:55+01:00",
  "deleted": false,
  "hour_rate": 100.0,
  "hour_rate_in_cents": 10000,
  "creator_id": null,
  "updater_id": 5151,
  "external_id": null,
  "entry_ids": [],
  "suggestion_id": null,
  "draft": false,
  "manage": true,
  "forecast_id": null,
  "billed_at": null,
  "locked_reason": null,
  "locked": false,
  "invoice_id": null,
  "timestamps": []
}

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/2089/bulk/events" -d '{"update":[{"id":3485,"note":"updated","billed":true}]}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer g3U36vz9S4iW21yE-P7u7B5TTvhQANWFSpRKKPDQf-g" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/bulk/events

POST /1.1/2089/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer g3U36vz9S4iW21yE-P7u7B5TTvhQANWFSpRKKPDQf-g

Parameters

{"update":[{"id":3485,"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": [
    3485
  ],
  "errors": {
    "create": [],
    "update": []
  }
}

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/2161/labels" -d '{"name":null,"label":{"name":"Web Programming","active":true}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer t8l1Lg63yREThmRrKtRMGQDRxq3mThgfeQUthU2aIIc" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/labels

POST /1.1/2161/labels
Accept: application/json
Content-Type: application/json
Authorization: Bearer t8l1Lg63yREThmRrKtRMGQDRxq3mThgfeQUthU2aIIc

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": 217,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": "https://emoji.memorycdn.com/tw64/1f3f7-fe0f.png",
  "active": true,
  "children": []
}

Delete a label

Request

curl "https://api.timelyapp.com/1.1/2162/labels/218" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer nf8oWqw9lwLM8DWKuEC8tftY_SfQDkuKpUFdhrqjsBk" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/labels/:id

DELETE /1.1/2162/labels/218
Accept: application/json
Content-Type: application/json
Authorization: Bearer nf8oWqw9lwLM8DWKuEC8tftY_SfQDkuKpUFdhrqjsBk

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/2165/labels?parent_id=220" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer iIBClFPBZ0scwRgz26BjjyL54DnUtkfVm2l5m2RfC1k" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/labels

GET /1.1/2165/labels?parent_id=220
Accept: application/json
Content-Type: application/json
Authorization: Bearer iIBClFPBZ0scwRgz26BjjyL54DnUtkfVm2l5m2RfC1k

Parameters

parent_id: 220

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": 220,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": null,
  "active": true,
  "children": []
}

List all labels

Get all the tags present in user’s account.

Request

curl -g "https://api.timelyapp.com/1.1/2164/labels" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer OJkBFwDD-fghmpEciOqEt4mTXl9inLpmnx_gvgIQ0Sg" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/labels

GET /1.1/2164/labels
Accept: application/json
Content-Type: application/json
Authorization: Bearer OJkBFwDD-fghmpEciOqEt4mTXl9inLpmnx_gvgIQ0Sg

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/2163/labels/219" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer kgaiucTUrraWfWRwl35_c4YEBizeEQ0_TIBTuRbNrCI" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/labels/:id

GET /1.1/2163/labels/219
Accept: application/json
Content-Type: application/json
Authorization: Bearer kgaiucTUrraWfWRwl35_c4YEBizeEQ0_TIBTuRbNrCI

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": 219,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": null,
  "active": true,
  "children": []
}

Update a label

Request

curl "https://api.timelyapp.com/1.1/2166/labels/221" -d '{"name":null,"label":{"name":"updated name"}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer MdfU7W8IHDFvOgSM8tgiUisnfWxiCRJATDxOkTEtV6s" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/labels/:id

PUT /1.1/2166/labels/221
Accept: application/json
Content-Type: application/json
Authorization: Bearer MdfU7W8IHDFvOgSM8tgiUisnfWxiCRJATDxOkTEtV6s

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": 221,
  "name": "updated name",
  "sequence": 1,
  "parent_id": null,
  "emoji": "https://emoji.memorycdn.com/tw64/1f3f7-fe0f.png",
  "active": true,
  "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/2177/users/current/permissions" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer -xo-d8hV3rSyAGLAmQyZHZzgt_JF6yMvnjCKjomYWuo" \
    -H "Cookie: "

Endpoint

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

GET /1.1/2177/users/current/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer -xo-d8hV3rSyAGLAmQyZHZzgt_JF6yMvnjCKjomYWuo

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": "user",
    "permissions": [
      "create",
      "read",
      "update",
      "delete",
      "notify"
    ]
  },
  {
    "resource": "project",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "label",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "company",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "team",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "account",
    "permissions": [
      "create",
      "read",
      "update",
      "manage_plan",
      "manage_subscriptions",
      "manage_dev"
    ]
  },
  {
    "resource": "report",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "forecast",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "invoice",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  }
]

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/2178/users/5321/permissions" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 9m9DDkamEqSIq1-qhfP3rLjLXVSgVqbgIyYc-Y79fjY" \
    -H "Cookie: "

Endpoint

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

GET /1.1/2178/users/5321/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer 9m9DDkamEqSIq1-qhfP3rLjLXVSgVqbgIyYc-Y79fjY

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": "user",
    "permissions": [
      "create",
      "read",
      "update",
      "delete",
      "notify"
    ]
  },
  {
    "resource": "project",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "label",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "company",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "team",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "account",
    "permissions": [
      "create",
      "read",
      "update",
      "manage_plan",
      "manage_subscriptions",
      "manage_dev"
    ]
  },
  {
    "resource": "report",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "forecast",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "invoice",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  }
]

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/2184/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,"client_id":1572,"budget_type":"M","budget":300,"users":[{"user_id":5333}],"budget_recurrence":{"recur":"week","start_date":"2018-09-21","end_date":"2019-09-21","recur_until":"end_date"},"labels":[{"label_id":222,"required":true},{"label_id":223,"required":true},{"label_id":224,"required":false},{"label_id":225,"required":false}]},"name":null}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YWDrWtc2r9eAF6Fro7Wq5-IVg_4-H5tW4SIM4eN-zNc" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/projects

POST /1.1/2184/projects
Accept: application/json
Content-Type: application/json
Authorization: Bearer YWDrWtc2r9eAF6Fro7Wq5-IVg_4-H5tW4SIM4eN-zNc

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,"client_id":1572,"budget_type":"M","budget":300,"users":[{"user_id":5333}],"budget_recurrence":{"recur":"week","start_date":"2018-09-21","end_date":"2019-09-21","recur_until":"end_date"},"labels":[{"label_id":222,"required":true},{"label_id":223,"required":true},{"label_id":224,"required":false},{"label_id":225,"required":false}]},"name":null}

Name	Description
project required	Project attributes
name required	Specifies the project name
color required	Specifies the project color. Example values: 47b17c, 67a3bc, bd4c4f, d0915a, 866b9c, cdae4f, 5ab8b7, c697c0
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“

Response

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

{
  "id": 2117,
  "active": true,
  "account_id": 2184,
  "name": "New Project",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "updated_at": 1640695683,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 1572,
    "name": "Vel repudiandae ad natus.",
    "active": true,
    "external_id": null,
    "updated_at": "2021-12-28T13:48:03+01:00"
  },
  "required_notes": false,
  "required_labels": false,
  "budget_expired_on": null,
  "has_recurrence": true,
  "enable_labels": "all",
  "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": 5333,
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "updated_at": "2021-12-28T13:48:03+01:00",
      "created_at": "2021-12-28T13:48:03+01:00",
      "deleted": false
    }
  ],
  "labels": [
    {
      "project_id": 2117,
      "label_id": 222,
      "budget": 0,
      "required": true,
      "updated_at": "2021-12-28T13:48:03+01:00"
    },
    {
      "project_id": 2117,
      "label_id": 223,
      "budget": 0,
      "required": true,
      "updated_at": "2021-12-28T13:48:03+01:00"
    },
    {
      "project_id": 2117,
      "label_id": 224,
      "budget": 0,
      "required": false,
      "updated_at": "2021-12-28T13:48:03+01:00"
    },
    {
      "project_id": 2117,
      "label_id": 225,
      "budget": 0,
      "required": false,
      "updated_at": "2021-12-28T13:48:03+01:00"
    }
  ],
  "label_ids": [
    222,
    223,
    224,
    225
  ],
  "required_label_ids": [
    222,
    223
  ],
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "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
  },
  "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
  },
  "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": "2021-12-28T13:48:03+01:00"
  }
}

Delete a project

Request

curl "https://api.timelyapp.com/1.1/2185/projects/2118" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ZzyL9M5eMzQwwS8HcrfIYmJJfBgyF9CKK0Jtyk9V2jk" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/projects/:id

DELETE /1.1/2185/projects/2118
Accept: application/json
Content-Type: application/json
Authorization: Bearer ZzyL9M5eMzQwwS8HcrfIYmJJfBgyF9CKK0Jtyk9V2jk

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/2187/projects" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer OZRISA5lN976b8agb2g1yBRVed7oHWi83NKASEgBRVk" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/projects

GET /1.1/2187/projects
Accept: application/json
Content-Type: application/json
Authorization: Bearer OZRISA5lN976b8agb2g1yBRVed7oHWi83NKASEgBRVk

Parameters

Name	Description
offset	Retrieve projects from offset
limit	Retrieve number of projects
sort	Field to sort projects by (Default updated_at)
order	Sorting order (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

Response

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

[
  {
    "id": 2120,
    "active": true,
    "account_id": 2187,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1640695684,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 1575,
      "name": "Fugit dolor quo adipisci.",
      "active": true,
      "external_id": null,
      "updated_at": "2021-12-28T13:48:04+01:00"
    },
    "required_notes": false,
    "required_labels": false,
    "budget_expired_on": null,
    "has_recurrence": false,
    "enable_labels": "all",
    "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": 5339,
        "hour_rate": 100.0,
        "hour_rate_in_cents": 10000.0,
        "updated_at": "2021-12-28T13:48:04+01:00",
        "created_at": "2021-12-28T13:48:04+01:00",
        "deleted": false
      }
    ],
    "labels": [],
    "label_ids": [],
    "required_label_ids": [],
    "cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0
    },
    "estimated_cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0
    },
    "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
    },
    "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
    },
    "unbilled_duration": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "formatted": "00:00",
      "total_hours": 0.0,
      "total_seconds": 0,
      "total_minutes": 0
    }
  }
]

Retrieve a project

Retrieve a single project by using its ID.

Request

curl -g "https://api.timelyapp.com/1.1/2186/projects/2119" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ccwVJOobartMB8QX-7KnNSm3dDE5YLhanPvxl5-zPSI" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/projects/:id

GET /1.1/2186/projects/2119
Accept: application/json
Content-Type: application/json
Authorization: Bearer ccwVJOobartMB8QX-7KnNSm3dDE5YLhanPvxl5-zPSI

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": 2119,
  "active": true,
  "account_id": 2186,
  "name": "Timely",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "updated_at": 1640695684,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 1574,
    "name": "Itaque fugit dolor iure.",
    "active": true,
    "external_id": null,
    "updated_at": "2021-12-28T13:48:04+01:00"
  },
  "required_notes": false,
  "required_labels": false,
  "budget_expired_on": null,
  "has_recurrence": false,
  "enable_labels": "all",
  "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": 5337,
      "hour_rate": 100.0,
      "hour_rate_in_cents": 10000.0,
      "updated_at": "2021-12-28T13:48:04+01:00",
      "created_at": "2021-12-28T13:48:04+01:00",
      "deleted": false
    }
  ],
  "labels": [],
  "label_ids": [],
  "required_label_ids": [],
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "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
  },
  "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
  },
  "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
}

Update a project

Request

curl "https://api.timelyapp.com/1.1/2189/projects/2122" -d '{"project":{"name":"updated project name","name":null}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer N_4JCHntIEsZfbqqnh7z3a0lT3JBFwN2OSFOzmIH5Cw" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/projects/:id

PUT /1.1/2189/projects/2122
Accept: application/json
Content-Type: application/json
Authorization: Bearer N_4JCHntIEsZfbqqnh7z3a0lT3JBFwN2OSFOzmIH5Cw

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] required	Specifies the project color. It should be one of these: 47b17c, 67a3bc, bd4c4f, d0915a, 866b9c, cdae4f, 5ab8b7, c697c0
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

Response

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

{
  "id": 2122,
  "active": true,
  "account_id": 2189,
  "name": "Timely",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "updated_at": 1640695684,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 1577,
    "name": "Quasi reiciendis necessitatibus et.",
    "active": true,
    "external_id": null,
    "updated_at": "2021-12-28T13:48:04+01:00"
  },
  "required_notes": false,
  "required_labels": false,
  "budget_expired_on": null,
  "has_recurrence": false,
  "enable_labels": "none",
  "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": 5343,
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "updated_at": "2021-12-28T13:48:04+01:00",
      "created_at": "2021-12-28T13:48:04+01:00",
      "deleted": false
    }
  ],
  "labels": [],
  "label_ids": [],
  "required_label_ids": [],
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "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
  },
  "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
  },
  "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
}

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/2225/reports" -d '{"user_ids":"5448","since":"2018-01-01","until":"2019-01-01","project_ids":"2207"}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Uq03iQKywlseOmI9fU5vKooAPnirJpsAZuUrOchCE9c" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/reports

POST /1.1/2225/reports
Accept: application/json
Content-Type: application/json
Authorization: Bearer Uq03iQKywlseOmI9fU5vKooAPnirJpsAZuUrOchCE9c

Parameters

{"user_ids":"5448","since":"2018-01-01","until":"2019-01-01","project_ids":"2207"}

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"

Response

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

[
  {
    "id": 1613,
    "name": "Dolore incidunt ut sit.",
    "projects": [
      {
        "id": 2207,
        "active": true,
        "account_id": 2225,
        "name": "Timely",
        "color": "67a3bc",
        "rate_type": "project",
        "billable": true,
        "updated_at": 1640695693,
        "external_id": null,
        "budget_scope": null,
        "client": {
          "id": 1613,
          "name": "Dolore incidunt ut sit.",
          "active": true,
          "external_id": null,
          "updated_at": "2021-12-28T13:48:13+01:00"
        },
        "required_notes": false,
        "required_labels": false,
        "budget_expired_on": null,
        "has_recurrence": false,
        "enable_labels": "all",
        "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
        },
        "estimated_cost": {
          "fractional": 80000,
          "formatted": "$800.00",
          "amount": 800.0
        },
        "billed_cost": {
          "fractional": 0,
          "formatted": "$0.00",
          "amount": 0.0
        },
        "unbilled_cost": {
          "fractional": 50000,
          "formatted": "$500.00",
          "amount": 500.0
        }
      }
    ],
    "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
    },
    "estimated_cost": {
      "fractional": 80000,
      "formatted": "$800.00",
      "amount": 800.0
    },
    "billed_cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0
    },
    "unbilled_cost": {
      "fractional": 50000,
      "formatted": "$500.00",
      "amount": 500.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/2226/reports/filter" -d '{"user_ids":"5450","since":"2018-01-01","until":"2019-01-01","project_ids":"2208"}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer bmOy0mnCOPNsdU8Eg1oramYWe87Q3VFaD1zTNbyrKDo" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/reports/filter

POST /1.1/2226/reports/filter
Accept: application/json
Content-Type: application/json
Authorization: Bearer bmOy0mnCOPNsdU8Eg1oramYWe87Q3VFaD1zTNbyrKDo

Parameters

{"user_ids":"5450","since":"2018-01-01","until":"2019-01-01","project_ids":"2208"}

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]
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).

Response

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

{
  "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
    },
    "estimated_cost": {
      "fractional": 80000,
      "formatted": "$800.00",
      "amount": 800.0
    },
    "billed_cost": {
      "fractional": 0,
      "formatted": "$0.00",
      "amount": 0.0
    },
    "unbilled_cost": {
      "fractional": 50000,
      "formatted": "$500.00",
      "amount": 500.0
    }
  },
  "clients": [
    {
      "id": 1614,
      "name": "Modi cum quia dicta.",
      "projects": [
        {
          "id": 2208,
          "active": true,
          "account_id": 2226,
          "name": "Timely",
          "color": "67a3bc",
          "rate_type": "project",
          "billable": true,
          "updated_at": 1640695693,
          "external_id": null,
          "budget_scope": null,
          "client": {
            "id": 1614,
            "name": "Modi cum quia dicta.",
            "active": true,
            "external_id": null,
            "updated_at": "2021-12-28T13:48:13+01:00"
          },
          "required_notes": false,
          "required_labels": false,
          "budget_expired_on": null,
          "has_recurrence": false,
          "enable_labels": "all",
          "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
          },
          "estimated_cost": {
            "fractional": 80000,
            "formatted": "$800.00",
            "amount": 800.0
          },
          "billed_cost": {
            "fractional": 0,
            "formatted": "$0.00",
            "amount": 0.0
          },
          "unbilled_cost": {
            "fractional": 50000,
            "formatted": "$500.00",
            "amount": 500.0
          }
        }
      ],
      "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
      },
      "estimated_cost": {
        "fractional": 80000,
        "formatted": "$800.00",
        "amount": 800.0
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0
      },
      "unbilled_cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0
      }
    }
  ],
  "users": [
    {
      "id": 5450,
      "email": "marijahxqazwxl@timelyapp.com",
      "name": "Marija Petrovic",
      "time_zone": "Europe/Paris",
      "updated_at": 1640695693,
      "active": false,
      "deleted": false,
      "memory_onboarded": true,
      "day_view_onboarded": true,
      "last_received_memories_date": null,
      "date_format": "dmy",
      "time_format": "24",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/cfb16a6a0ffe48f4db45ff91691df944?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/cfb16a6a0ffe48f4db45ff91691df944?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/cfb16a6a0ffe48f4db45ff91691df944?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/cfb16a6a0ffe48f4db45ff91691df944?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/cfb16a6a0ffe48f4db45ff91691df944?d=http%3A%2F%2Fapp.timelyapp.local%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
      },
      "estimated_cost": {
        "fractional": 80000,
        "formatted": "$800.00",
        "amount": 800.0
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0
      },
      "unbilled_cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0
      }
    }
  ],
  "labels": [
    {
      "id": 0,
      "name": "Untagged",
      "sequence": -1,
      "parent_id": null,
      "emoji": "https://emoji.memorycdn.com/tw64/1f3f7.png",
      "active": true,
      "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
      },
      "estimated_cost": {
        "fractional": 80000,
        "formatted": "$800.00",
        "amount": 800.0
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0
      },
      "unbilled_cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.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
      },
      "estimated_cost": {
        "fractional": 40000,
        "formatted": "$400.00",
        "amount": 400.0
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0
      },
      "unbilled_cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.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
      },
      "estimated_cost": {
        "fractional": 40000,
        "formatted": "$400.00",
        "amount": 400.0
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0
      },
      "unbilled_cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.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
      },
      "estimated_cost": {
        "fractional": 80000,
        "formatted": "$800.00",
        "amount": 800.0
      },
      "billed_cost": {
        "fractional": 0,
        "formatted": "$0.00",
        "amount": 0.0
      },
      "unbilled_cost": {
        "fractional": 50000,
        "formatted": "$500.00",
        "amount": 500.0
      }
    }
  ]
}

Roles

List roles

Note: default attribute shows which role to select by default

Request

curl -g "https://api.timelyapp.com/1.1/2227/roles" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer v9TmGCldRtNaXlUOiQDJzbrjc0KTQDtsWuQeaB-Il1A" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/roles

GET /1.1/2227/roles
Accept: application/json
Content-Type: application/json
Authorization: Bearer v9TmGCldRtNaXlUOiQDJzbrjc0KTQDtsWuQeaB-Il1A

Parameters

Name	Description
account_id	Account id for which roles are required

Response

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

[
  {
    "id": 6679,
    "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
  },
  {
    "id": 6681,
    "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
  },
  {
    "id": 6680,
    "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
  }
]

Teams

The team object shows all teams available on an account.

Create a team

Request

curl "https://api.timelyapp.com/1.1/2249/teams" -d '{"name":null,"team":{"name":"Timely","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":5496,"lead":true},{"user_id":5498,"lead":false}]}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer p73ZzMfu8MAC1qm6u5017sLyB1ZkmVxleyoOJXfEQNM" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/teams

POST /1.1/2249/teams
Accept: application/json
Content-Type: application/json
Authorization: Bearer p73ZzMfu8MAC1qm6u5017sLyB1ZkmVxleyoOJXfEQNM

Parameters

{"name":null,"team":{"name":"Timely","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":5496,"lead":true},{"user_id":5498,"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": 49,
  "name": "Timely",
  "color": "67a3bc",
  "emoji": "http://path.to/emoji.png",
  "external_id": null,
  "user_ids": [
    5496,
    5498
  ],
  "users": [
    {
      "id": 61,
      "user_id": 5496,
      "team_id": 49,
      "lead": true
    },
    {
      "id": 62,
      "user_id": 5498,
      "team_id": 49,
      "lead": false
    }
  ]
}

Delete a team

Request

curl "https://api.timelyapp.com/1.1/2250/teams/50" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer eQndq2gv-WBBa-ytIyJbmlbBhIKQAlALHHxY44g2t-Y" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/teams/:id

DELETE /1.1/2250/teams/50
Accept: application/json
Content-Type: application/json
Authorization: Bearer eQndq2gv-WBBa-ytIyJbmlbBhIKQAlALHHxY44g2t-Y

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

Response

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

{}

List all teams

Request

curl -g "https://api.timelyapp.com/1.1/2252/teams" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer nIOPZ94mcoDeUcfFNnS6JQasxz7EF6S45QOuUvvJ93U" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/teams

GET /1.1/2252/teams
Accept: application/json
Content-Type: application/json
Authorization: Bearer nIOPZ94mcoDeUcfFNnS6JQasxz7EF6S45QOuUvvJ93U

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": 52,
    "name": "Timely",
    "color": "67a3bc",
    "emoji": "http://path.to/emoji.png",
    "external_id": null,
    "user_ids": [],
    "users": []
  }
]

Retrieve a team

Request

curl -g "https://api.timelyapp.com/1.1/2251/teams/51" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer _0v8DDigxKvhIYTZrB1r8-V7wKq22cbhyQTwhFiLny4" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/teams/:id

GET /1.1/2251/teams/51
Accept: application/json
Content-Type: application/json
Authorization: Bearer _0v8DDigxKvhIYTZrB1r8-V7wKq22cbhyQTwhFiLny4

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": 51,
  "name": "Timely",
  "color": "67a3bc",
  "emoji": "http://path.to/emoji.png",
  "external_id": null,
  "user_ids": [],
  "users": []
}

Update a team

Request

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

Endpoint

PUT /1.1/:account_id/teams/:id

PUT /1.1/2253/teams/53
Accept: application/json
Content-Type: application/json
Authorization: Bearer Y5ocFsSBCvpitk5Ydkp9V4gCfWC6YOqiAnLmmmgyaUg

Parameters

{"name":null,"team":{"name":"Backend","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":5505,"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}]

Response

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

{
  "id": 53,
  "name": "Backend",
  "color": "67a3bc",
  "emoji": "http://path.to/emoji.png",
  "external_id": null,
  "user_ids": [
    5505
  ],
  "users": [
    {
      "id": 63,
      "user_id": 5505,
      "team_id": 53,
      "lead": true
    }
  ]
}

UserCapacities

Retrieve capacities

See capacities of multiple users in the account

Request

curl -g "https://api.timelyapp.com/1.1/2258/users/capacities" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer _LwHzUGajMK6ckk3YlHwGq8qIzCAo0zt71t91j7eV6M" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/capacities

GET /1.1/2258/users/capacities
Accept: application/json
Content-Type: application/json
Authorization: Bearer _LwHzUGajMK6ckk3YlHwGq8qIzCAo0zt71t91j7eV6M

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": 5515,
    "capacities": [
      {
        "id": null,
        "weekly_capacity": 40.0,
        "daily_capacity": 8.0,
        "weekdays": "MO,TU,WE,TH,FR",
        "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/2257/users/5513/capacities" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer dwxBZrtEgFZAbBKIigO9Cn5byacO1a152199_vvV_40" \
    -H "Cookie: "

Endpoint

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

GET /1.1/2257/users/5513/capacities
Accept: application/json
Content-Type: application/json
Authorization: Bearer dwxBZrtEgFZAbBKIigO9Cn5byacO1a152199_vvV_40

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",
    "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/2260/users" -d '{"user":{"name":"Marija Petrovic","email":"marija@timely.com","user_level":"normal","admin":false,"projects":[{"project_id":2241,"hour_rate":10}]},"name":null,"admin":{"id":1795,"email":"notifications@timelyapp.com","created_at":"2021-12-28T13:48:20.000+01:00","updated_at":"2021-12-28T13:48:20.000+01:00","name":"Timely","notifier":false}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer V3nZ3seNNxwk2L472VjIp2AJDFZnbCVGel24HuxUg-I" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/users

POST /1.1/2260/users
Accept: application/json
Content-Type: application/json
Authorization: Bearer V3nZ3seNNxwk2L472VjIp2AJDFZnbCVGel24HuxUg-I

Parameters

{"user":{"name":"Marija Petrovic","email":"marija@timely.com","user_level":"normal","admin":false,"projects":[{"project_id":2241,"hour_rate":10}]},"name":null,"admin":{"id":1795,"email":"notifications@timelyapp.com","created_at":"2021-12-28T13:48:20.000+01:00","updated_at":"2021-12-28T13:48:20.000+01:00","name":"Timely","notifier":false}}

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

Response

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

{
  "id": 5521,
  "email": "marija@timely.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": false,
  "memory_onboarded": false,
  "created_at": 1640695700,
  "updated_at": 1640695700,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Etc/UTC",
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
  },
  "type": "User",
  "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": 6779,
  "role": {
    "id": 6779,
    "name": "manager"
  }
}

Delete a user

Request

curl "https://api.timelyapp.com/1.1/2261/users/5522" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer UWG-Yh1DWV0AqShH6wjZ7nOgNBCXmZkLtBPxxL_BdoY" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/users/:id

DELETE /1.1/2261/users/5522
Accept: application/json
Content-Type: application/json
Authorization: Bearer UWG-Yh1DWV0AqShH6wjZ7nOgNBCXmZkLtBPxxL_BdoY

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 10 most recently updated users.

Request

curl -g "https://api.timelyapp.com/1.1/2264/users" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer AQY9-XZ8my9Ew0c5nJzwQ19gmQqr1VqispMaTixXuw8" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users

GET /1.1/2264/users
Accept: application/json
Content-Type: application/json
Authorization: Bearer AQY9-XZ8my9Ew0c5nJzwQ19gmQqr1VqispMaTixXuw8

Parameters

Name	Description
account_id	The account ID containing the users you want to retrieve
limit	Retrieve a limited number of users
offset	Retrieve users from offset
order	Sorting order on updated_at
filter	Filter users - Ex: filter=deleted

Response

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

[
  {
    "id": 5528,
    "email": "marijamjqeyqfk@timelyapp.com",
    "name": "Marija Petrovic",
    "active": false,
    "day_view_onboarded": true,
    "memory_onboarded": true,
    "created_at": 1640695701,
    "updated_at": 1640695701,
    "last_received_memories_date": null,
    "sign_in_count": null,
    "external_id": null,
    "time_zone": "Europe/Paris",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/6b32d478bf192e430bb0faa963d04b24?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/6b32d478bf192e430bb0faa963d04b24?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
      "medium_retina": "https://www.gravatar.com/avatar/6b32d478bf192e430bb0faa963d04b24?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/6b32d478bf192e430bb0faa963d04b24?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
      "small_retina": "https://www.gravatar.com/avatar/6b32d478bf192e430bb0faa963d04b24?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
      "small": "https://www.gravatar.com/avatar/6b32d478bf192e430bb0faa963d04b24?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
    },
    "type": "User",
    "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": 6790,
    "role": {
      "id": 6790,
      "name": "admin"
    }
  }
]

Retrieve a user

Request

curl -g "https://api.timelyapp.com/1.1/2262/users/5524" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer xmrKdkzoy1NspRHvwD3pX6dH8-wSMOeh-LI6vSzp0Qc" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/:id

GET /1.1/2262/users/5524
Accept: application/json
Content-Type: application/json
Authorization: Bearer xmrKdkzoy1NspRHvwD3pX6dH8-wSMOeh-LI6vSzp0Qc

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": 5524,
  "email": "marijajugnxnsv@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1640695700,
  "updated_at": 1640695700,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/65df77b75ce61dab076ef2c8ed2b16d4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/65df77b75ce61dab076ef2c8ed2b16d4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/65df77b75ce61dab076ef2c8ed2b16d4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/65df77b75ce61dab076ef2c8ed2b16d4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/65df77b75ce61dab076ef2c8ed2b16d4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/65df77b75ce61dab076ef2c8ed2b16d4?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
  },
  "type": "User",
  "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": 6784,
  "role": {
    "id": 6784,
    "name": "admin"
  }
}

Retrieve current user

Request

curl -g "https://api.timelyapp.com/1.1/2263/users/current" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer KQTpxImWLA3wh_N1YeojXIGWOrtSNInzqggyOczMb3g" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users/current

GET /1.1/2263/users/current
Accept: application/json
Content-Type: application/json
Authorization: Bearer KQTpxImWLA3wh_N1YeojXIGWOrtSNInzqggyOczMb3g

Parameters

Name	Description
account_id	The account ID containing the current user

Response

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

{
  "id": 5526,
  "email": "marijardekqdxk@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1640695701,
  "updated_at": 1640695701,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/efba24c44506ddb42e1a5bdc988f7401?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/efba24c44506ddb42e1a5bdc988f7401?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/efba24c44506ddb42e1a5bdc988f7401?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/efba24c44506ddb42e1a5bdc988f7401?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/efba24c44506ddb42e1a5bdc988f7401?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/efba24c44506ddb42e1a5bdc988f7401?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
  },
  "type": "User",
  "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": 6787,
  "role": {
    "id": 6787,
    "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/2265/users/5530" -d '{"user":{"admin":{"id":1800,"email":"notifications@timelyapp.com","created_at":"2021-12-28T13:48:21.000+01:00","updated_at":"2021-12-28T13:48:21.000+01:00","name":"Timely","notifier":false},"role_id":6793,"projects":[{"project_id":2246,"hour_rate":10}]}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Gz6q1_z2cWrj8L_TM3v_3-TUy7yg4_liSENeAJUU3jQ" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/users/:id

PUT /1.1/2265/users/5530
Accept: application/json
Content-Type: application/json
Authorization: Bearer Gz6q1_z2cWrj8L_TM3v_3-TUy7yg4_liSENeAJUU3jQ

Parameters

{"user":{"admin":{"id":1800,"email":"notifications@timelyapp.com","created_at":"2021-12-28T13:48:21.000+01:00","updated_at":"2021-12-28T13:48:21.000+01:00","name":"Timely","notifier":false},"role_id":6793,"projects":[{"project_id":2246,"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
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
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

Response

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

{
  "id": 5530,
  "email": "marijagjszmipm@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1640695701,
  "updated_at": 1640695701,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/ef0ed0a1ad33b4f0631ae2c2ee369481?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/ef0ed0a1ad33b4f0631ae2c2ee369481?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/ef0ed0a1ad33b4f0631ae2c2ee369481?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/ef0ed0a1ad33b4f0631ae2c2ee369481?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/ef0ed0a1ad33b4f0631ae2c2ee369481?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/ef0ed0a1ad33b4f0631ae2c2ee369481?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
  },
  "type": "User",
  "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": 6793,
  "role": {
    "id": 6793,
    "name": "admin"
  }
}

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.