NAV Navbar
cURL

Introduction

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

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

Authentication

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

Create an OAuth Application (only available to the Admin User): https://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 trHuEdOd_1QAJ2rND9e1ssPPEWimPenhhw1etBVLspI" \
    -H "Cookie: "

Endpoint

GET /1.1/accounts

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

Parameters

None known.

Response

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

[
  {
    "id": 12010,
    "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-9aefd4c1fb903fb750d36f1b1cc64dc01eb578efd2fd0eb5311344082d6d036e.png",
      "medium_retina": "/assets/account_thumbs/account_medium_retina-3e55e5ac5ba6b1d8077c1e329691e55032a5831997c9e712998594192d534fdf.png",
      "small_retina": "/assets/account_thumbs/account_small_retina-1b8bfb705765064d856161ba9daa1d52155f181c330ac6fe9b5e2f366adaf4fe.png",
      "brand_logo": false
    },
    "from": "Web",
    "max_users": 0,
    "seats": 1,
    "num_users": 1,
    "max_projects": 0,
    "num_projects": 0,
    "plan_id": 13370,
    "plan_name": "Essential",
    "next_charge": "2020-04-30",
    "start_of_week": 0,
    "created_at": 1585672417,
    "payment_mode": "web",
    "paid": true,
    "company_size": "10-49",
    "plan_code": "essential",
    "plan_custom": false,
    "appstore_transaction_id": null,
    "owner_id": 28192,
    "weekly_user_capacity": 40.0,
    "capacity": {
      "hours": 40.0,
      "minutes": 0.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": "planning",
        "days": -1
      },
      {
        "name": "people_dashboard",
        "days": -1
      },
      {
        "name": "people_notify",
        "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/12008/activities" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer LnlT3UN5Vcn1krS_DWu_m4mwKyU8Z340-7XqwnJDOww" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/activities

GET /1.1/12008/activities
Accept: application/json
Content-Type: application/json
Authorization: Bearer LnlT3UN5Vcn1krS_DWu_m4mwKyU8Z340-7XqwnJDOww

Parameters

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

Response

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

[

]

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

Endpoint

GET /1.1/accounts/:id

GET /1.1/accounts/12009
Accept: application/json
Content-Type: application/json
Authorization: Bearer P6iv5m2HLuF-cK6jOFG98hdGCUgjdaVm7lNRrt83pZI

Parameters

Name Description
id The id of the account to be retrieved

Response

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

{
  "id": 12009,
  "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-9aefd4c1fb903fb750d36f1b1cc64dc01eb578efd2fd0eb5311344082d6d036e.png",
    "medium_retina": "/assets/account_thumbs/account_medium_retina-3e55e5ac5ba6b1d8077c1e329691e55032a5831997c9e712998594192d534fdf.png",
    "small_retina": "/assets/account_thumbs/account_small_retina-1b8bfb705765064d856161ba9daa1d52155f181c330ac6fe9b5e2f366adaf4fe.png",
    "brand_logo": false
  },
  "from": "Web",
  "max_users": 0,
  "seats": 1,
  "num_users": 1,
  "max_projects": 0,
  "num_projects": 0,
  "plan_id": 13369,
  "plan_name": "Essential",
  "next_charge": "2020-04-30",
  "start_of_week": 0,
  "created_at": 1585672417,
  "payment_mode": "web",
  "paid": true,
  "company_size": "10-49",
  "plan_code": "essential",
  "plan_custom": false,
  "appstore_transaction_id": null,
  "owner_id": 28190,
  "weekly_user_capacity": 40.0,
  "capacity": {
    "hours": 40.0,
    "minutes": 0.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": "planning",
      "days": -1
    },
    {
      "name": "people_dashboard",
      "days": -1
    },
    {
      "name": "people_notify",
      "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/12032/clients" -d '{"client":{"name":"Timely","active":true}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 2s-pgRThh9UtcBEBHEfbug-wVHUdatZ3FGbNh-551YM" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/clients

POST /1.1/12032/clients
Accept: application/json
Content-Type: application/json
Authorization: Bearer 2s-pgRThh9UtcBEBHEfbug-wVHUdatZ3FGbNh-551YM

Parameters

{"client":{"name":"Timely","active":true}}
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": 7754,
  "name": "Timely",
  "active": true,
  "external_id": null,
  "updated_at": "2020-03-31T18:33:41+02:00"
}

List all clients

Client lists will return your 10 most recently updated clients. Additionally, you can add the “per_page”, “filter” and “order” optional parameters to change the result

NOTE: Client list will return recently updated 10 clients.

Request

curl -g "https://api.timelyapp.com/1.1/12033/clients" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer H88KWea4_Tf2wWjbWW9mC0jC2V9YY-VjbJkK-jK5WlY" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/clients

GET /1.1/12033/clients
Accept: application/json
Content-Type: application/json
Authorization: Bearer H88KWea4_Tf2wWjbWW9mC0jC2V9YY-VjbJkK-jK5WlY

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": 7755,
    "name": "Timely",
    "active": true,
    "external_id": null,
    "updated_at": "2020-03-31T18:33:41+02:00"
  }
]

Update a client

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

Request

curl "https://api.timelyapp.com/1.1/12034/clients/7756" -d '{"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 IDdzNOAMDpdHyiZmKDUVyWXQ74ZcsXjKCHSBu8Ygk7I" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/clients/:id

PUT /1.1/12034/clients/7756
Accept: application/json
Content-Type: application/json
Authorization: Bearer IDdzNOAMDpdHyiZmKDUVyWXQ74ZcsXjKCHSBu8Ygk7I

Parameters

{"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": 7756,
  "name": "Updated name",
  "active": true,
  "external_id": null,
  "updated_at": "2020-03-31T18:33:42+02: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/12051/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2020-03-31T18:33:44.290+02:00","to":"2020-03-31T22:03:44.290+02:00","day":"2020-03-31","note":"Notes for testing with some random #hash in it.","billed":false,"hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":11205}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer -IyR_pxjANkd42LMYiRMReGpdLiSRL_GVQrb5t_UtR8" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/events

POST /1.1/12051/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer -IyR_pxjANkd42LMYiRMReGpdLiSRL_GVQrb5t_UtR8

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2020-03-31T18:33:44.290+02:00","to":"2020-03-31T22:03:44.290+02:00","day":"2020-03-31","note":"Notes for testing with some random #hash in it.","billed":false,"hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":11205}}
Name Description
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": 10836,
  "uid": "97e49161287e7a4f9b745366e4f9431b",
  "user": {
    "id": 28279,
    "email": "marijahhzegyub@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/ffb466a700c35b8cb71902e8fe8e8388?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/ffb466a700c35b8cb71902e8fe8e8388?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/ffb466a700c35b8cb71902e8fe8e8388?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:44+02:00"
  },
  "project": {
    "id": 11205,
    "active": true,
    "account_id": 12051,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672424,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7762,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:44+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "cost": {
    "fractional": 17500,
    "formatted": "$175.00",
    "amount": 175.0
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "day": "2020-03-31",
  "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": 1585672424,
  "created_at": 1585672424,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "to": "2020-03-31T22:03:44+02:00",
  "from": "2020-03-31T18:33:44+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": 28279,
  "updater_id": 28279,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

Create an event for a project

Note: Normal user can add hours to existing projects from account. Limited user can add hours to only his projects.

Request

curl "https://api.timelyapp.com/1.1/12050/projects/11204/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2020-03-31T18:33:44.044+02:00","to":"2020-03-31T22:03:44.044+02:00","day":"2020-03-31","note":"Notes for testing with some random #hash in it.","billed":false,"hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":11204}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Djj6751p4Qc2c1usmCWrcuuMq6kAJ7e1WI1xdoLzwpM" \
    -H "Cookie: "

Endpoint

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

POST /1.1/12050/projects/11204/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer Djj6751p4Qc2c1usmCWrcuuMq6kAJ7e1WI1xdoLzwpM

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2020-03-31T18:33:44.044+02:00","to":"2020-03-31T22:03:44.044+02:00","day":"2020-03-31","note":"Notes for testing with some random #hash in it.","billed":false,"hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":11204}}
Name Description
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": 10835,
  "uid": "8c12cbc89eb07068855968f976662a18",
  "user": {
    "id": 28277,
    "email": "marijaedvrmdrm@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/0182a0235230025b5fc8abb8cb77feeb?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/0182a0235230025b5fc8abb8cb77feeb?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/0182a0235230025b5fc8abb8cb77feeb?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:43+02:00"
  },
  "project": {
    "id": 11204,
    "active": true,
    "account_id": 12050,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672424,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7761,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:44+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "cost": {
    "fractional": 17500,
    "formatted": "$175.00",
    "amount": 175.0
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "day": "2020-03-31",
  "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": 1585672424,
  "created_at": 1585672424,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "to": "2020-03-31T22:03:44+02:00",
  "from": "2020-03-31T18:33:44+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": 28277,
  "updater_id": 28277,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

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/12049/users/28275/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2020-03-31T18:33:43.790+02:00","to":"2020-03-31T22:03:43.790+02:00","day":"2020-03-31","note":"Notes for testing with some random #hash in it.","billed":false,"hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":28275}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer _NtNGeyDIF7lySNj9vsOAmwqvDgUitSp_bds4pEqeKM" \
    -H "Cookie: "

Endpoint

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

POST /1.1/12049/users/28275/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer _NtNGeyDIF7lySNj9vsOAmwqvDgUitSp_bds4pEqeKM

Parameters

{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2020-03-31T18:33:43.790+02:00","to":"2020-03-31T22:03:43.790+02:00","day":"2020-03-31","note":"Notes for testing with some random #hash in it.","billed":false,"hour_rate":100,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":28275}}
Name Description
day required Event day
hours required Event hours
minutes required Event minutes
user_id required The numerical ID of the desired user. Example values: 123

Response

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

{
  "id": 10834,
  "uid": "d69c7ebb6a253532b266151eac6591af",
  "user": {
    "id": 28275,
    "email": "marijajwzoxbpq@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/653db4a9fa133a3991ce5bf17a85a44e?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/653db4a9fa133a3991ce5bf17a85a44e?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/653db4a9fa133a3991ce5bf17a85a44e?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:43+02:00"
  },
  "project": {
    "id": 11203,
    "active": true,
    "account_id": 12049,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672423,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7760,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:43+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 0,
    "minutes": 0,
    "seconds": 0,
    "formatted": "00:00",
    "total_hours": 0.0,
    "total_seconds": 0,
    "total_minutes": 0
  },
  "cost": {
    "fractional": 17500,
    "formatted": "$175.00",
    "amount": 175.0
  },
  "estimated_cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "day": "2020-03-31",
  "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": 1585672423,
  "created_at": 1585672423,
  "created_from": "Timely",
  "updated_from": "Timely",
  "billed": false,
  "to": "2020-03-31T22:03:43+02:00",
  "from": "2020-03-31T18:33:43+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": 28275,
  "updater_id": 28275,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

Delete an event

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

Request

curl "https://api.timelyapp.com/1.1/12052/events/10837" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer d_-jGBcvfliGsWs_tt2VkUMb0bXgryDhtX1AYCphcYY" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/events/:id

DELETE /1.1/12052/events/10837
Accept: application/json
Content-Type: application/json
Authorization: Bearer d_-jGBcvfliGsWs_tt2VkUMb0bXgryDhtX1AYCphcYY

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

{
}

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

Endpoint

GET /1.1/:account_id/events

GET /1.1/12054/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer nSpXRJ37E2pQzcC_1s1nhfvyxJBFAebT4nv4oBofQkU

Parameters

Name Description
account_id The account ID containing 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

Response

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

[
  {
    "id": 10839,
    "uid": "0f79c3f3e971e1af245a3551b53a8737",
    "user": {
      "id": 28285,
      "email": "marijapwkhcywm@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "timeline": "https://www.gravatar.com/avatar/d5f98bafc3c57fef85a7cc023385c511?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/d5f98bafc3c57fef85a7cc023385c511?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/d5f98bafc3c57fef85a7cc023385c511?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
      },
      "updated_at": "2020-03-31T18:33:44+02:00"
    },
    "project": {
      "id": 11208,
      "active": true,
      "account_id": 12054,
      "name": "Timely",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "updated_at": 1585672425,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 7765,
        "name": "Timely",
        "active": true,
        "external_id": null,
        "updated_at": "2020-03-31T18:33:45+02:00"
      },
      "required_notes": false,
      "budget": 0,
      "budget_type": "",
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "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": 17500,
      "formatted": "$175.00",
      "amount": 175.0
    },
    "estimated_cost": {
      "fractional": 20000,
      "formatted": "$200.00",
      "amount": 200.0
    },
    "day": "2020-03-31",
    "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": 1585672425,
    "created_at": 1585672425,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "to": "2020-03-31T22:03:45+02:00",
    "from": "2020-03-31T18:33:45+02:00",
    "deleted": false,
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "creator_id": null,
    "updater_id": null,
    "external_id": null,
    "entry_ids": [

    ],
    "suggestion_id": null
  }
]

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/12056/projects/11210/events" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer l5UB9VU_i0Ij-9VPMTqFCRUeSMkTevaMPFSaSSrmUTc" \
    -H "Cookie: "

Endpoint

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

GET /1.1/12056/projects/11210/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer l5UB9VU_i0Ij-9VPMTqFCRUeSMkTevaMPFSaSSrmUTc

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

Response

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

[
  {
    "id": 10841,
    "uid": "24cceab7ffc1118f5daaace13c670885",
    "user": {
      "id": 28289,
      "email": "marijatmnscppw@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "timeline": "https://www.gravatar.com/avatar/7da1f0c51f3764aeeb5c86bb2682cf16?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/7da1f0c51f3764aeeb5c86bb2682cf16?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/7da1f0c51f3764aeeb5c86bb2682cf16?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
      },
      "updated_at": "2020-03-31T18:33:45+02:00"
    },
    "project": {
      "id": 11210,
      "active": true,
      "account_id": 12056,
      "name": "Timely",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "updated_at": 1585672425,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 7767,
        "name": "Timely",
        "active": true,
        "external_id": null,
        "updated_at": "2020-03-31T18:33:45+02:00"
      },
      "required_notes": false,
      "budget": 0,
      "budget_type": "",
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "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": 17500,
      "formatted": "$175.00",
      "amount": 175.0
    },
    "estimated_cost": {
      "fractional": 20000,
      "formatted": "$200.00",
      "amount": 200.0
    },
    "day": "2020-03-31",
    "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": 1585672425,
    "created_at": 1585672425,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "to": "2020-03-31T22:03:45+02:00",
    "from": "2020-03-31T18:33:45+02:00",
    "deleted": false,
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "creator_id": null,
    "updater_id": null,
    "external_id": null,
    "entry_ids": [

    ],
    "suggestion_id": null
  }
]

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/12055/users/28287/events" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer b68XmYW0gp-WeP9fcaYLZz7JkCE3R9CdbEPjp4vPgvs" \
    -H "Cookie: "

Endpoint

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

GET /1.1/12055/users/28287/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer b68XmYW0gp-WeP9fcaYLZz7JkCE3R9CdbEPjp4vPgvs

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

Response

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

[
  {
    "id": 10840,
    "uid": "033522d9bdf796d13c4b594cbdf03184",
    "user": {
      "id": 28287,
      "email": "marijayyodcnur@timelyapp.com",
      "name": "Marija Petrovic",
      "avatar": {
        "timeline": "https://www.gravatar.com/avatar/7d4542cb5bc05665c9e6983133fcdb62?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/7d4542cb5bc05665c9e6983133fcdb62?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/7d4542cb5bc05665c9e6983133fcdb62?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
      },
      "updated_at": "2020-03-31T18:33:45+02:00"
    },
    "project": {
      "id": 11209,
      "active": true,
      "account_id": 12055,
      "name": "Timely",
      "color": "67a3bc",
      "rate_type": "project",
      "billable": true,
      "updated_at": 1585672425,
      "external_id": null,
      "budget_scope": null,
      "client": {
        "id": 7766,
        "name": "Timely",
        "active": true,
        "external_id": null,
        "updated_at": "2020-03-31T18:33:45+02:00"
      },
      "required_notes": false,
      "budget": 0,
      "budget_type": "",
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "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": 17500,
      "formatted": "$175.00",
      "amount": 175.0
    },
    "estimated_cost": {
      "fractional": 20000,
      "formatted": "$200.00",
      "amount": 200.0
    },
    "day": "2020-03-31",
    "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": 1585672425,
    "created_at": 1585672425,
    "created_from": "Web",
    "updated_from": "Web",
    "billed": false,
    "to": "2020-03-31T22:03:45+02:00",
    "from": "2020-03-31T18:33:45+02:00",
    "deleted": false,
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "creator_id": null,
    "updater_id": null,
    "external_id": null,
    "entry_ids": [

    ],
    "suggestion_id": null
  }
]

Logged in user updating details and user of an event

Note: Normal users can change an event’s creator to another user on their account. Limited users cannot edit event details.

Request

curl "https://api.timelyapp.com/1.1/12061/users/28299/events/10846" -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 FnbTrUjj2-ED9Mr6jFUUYgjoQNIUXdxeQYMaIDXDXGU" \
    -H "Cookie: "

Endpoint

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

PUT /1.1/12061/users/28299/events/10846
Accept: application/json
Content-Type: application/json
Authorization: Bearer FnbTrUjj2-ED9Mr6jFUUYgjoQNIUXdxeQYMaIDXDXGU

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": 10846,
  "uid": "d5b2bbd3e57d6c19003667a447475589",
  "user": {
    "id": 28299,
    "email": "marijadwjharvq@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/f8db63eb35ceb4c29f0ece167de7298b?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/f8db63eb35ceb4c29f0ece167de7298b?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/f8db63eb35ceb4c29f0ece167de7298b?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:46+02:00"
  },
  "project": {
    "id": 11215,
    "active": true,
    "account_id": 12061,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672427,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7772,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:47+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2020-03-31",
  "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": 1585672427,
  "created_at": 1585672427,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "to": "2020-03-31T22:03:47+02:00",
  "from": "2020-03-31T18:33:47+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": null,
  "updater_id": 28299,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

Loggedin user updating details and project of their event

Request

curl "https://api.timelyapp.com/1.1/12060/projects/11214/events/10845" -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 _GSaWugr6bckFnp4j5M9kYj3ARxSyJQXyw1__zvEkCI" \
    -H "Cookie: "

Endpoint

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

PUT /1.1/12060/projects/11214/events/10845
Accept: application/json
Content-Type: application/json
Authorization: Bearer _GSaWugr6bckFnp4j5M9kYj3ARxSyJQXyw1__zvEkCI

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": 10845,
  "uid": "c8f5b1786c5c5f89edf17f37dbca107e",
  "user": {
    "id": 28297,
    "email": "marijatprsesxr@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/28d7e7e6be1445ff5b1f303e9551b37d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/28d7e7e6be1445ff5b1f303e9551b37d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/28d7e7e6be1445ff5b1f303e9551b37d?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:46+02:00"
  },
  "project": {
    "id": 11214,
    "active": true,
    "account_id": 12060,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672426,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7771,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:46+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2020-03-31",
  "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": 1585672426,
  "created_at": 1585672426,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "to": "2020-03-31T22:03:46+02:00",
  "from": "2020-03-31T18:33:46+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": null,
  "updater_id": 28297,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

Retrieve an event

Request

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

Endpoint

GET /1.1/:account_id/events/:id

GET /1.1/12053/events/10838
Accept: application/json
Content-Type: application/json
Authorization: Bearer Jt2ExfVjsWrT_9Oq4yzgcywuvUzMJyW2Y1FMYCG8BOM

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": 10838,
  "uid": "157792e4abb490f99dbd738483e0d2d4",
  "user": {
    "id": 28283,
    "email": "marijazwpcfdub@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/2105d207e87353a467980a2c41a397ec?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/2105d207e87353a467980a2c41a397ec?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/2105d207e87353a467980a2c41a397ec?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:44+02:00"
  },
  "project": {
    "id": 11207,
    "active": true,
    "account_id": 12053,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672424,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7764,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:44+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 17500,
    "formatted": "$175.00",
    "amount": 175.0
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2020-03-31",
  "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": 1585672424,
  "created_at": 1585672424,
  "created_from": "Web",
  "updated_from": "Web",
  "billed": false,
  "to": "2020-03-31T22:03:44+02:00",
  "from": "2020-03-31T18:33:44+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": null,
  "updater_id": null,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

Start timer on an event

Request

curl "https://api.timelyapp.com/1.1/12057/events/10842/start" -d '' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer z7pcr3XdmsdMzs-ifDAziy-We-xYGO5cif_tp9fyUAM" \
    -H "Cookie: "

Endpoint

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

PUT /1.1/12057/events/10842/start
Accept: application/json
Content-Type: application/json
Authorization: Bearer z7pcr3XdmsdMzs-ifDAziy-We-xYGO5cif_tp9fyUAM

Parameters

Name Description
id required Event ID

Response

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

{
  "id": 10842,
  "uid": "983c25c7ee9644953077c7f3cb15a8db",
  "user": {
    "id": 28291,
    "email": "marijazugujvex@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/b1345f7ee4f0b69db5cd8c4e412f37bd?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/b1345f7ee4f0b69db5cd8c4e412f37bd?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/b1345f7ee4f0b69db5cd8c4e412f37bd?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:45+02:00"
  },
  "project": {
    "id": 11211,
    "active": true,
    "account_id": 12057,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672425,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7768,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:45+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 17500,
    "formatted": "$175.00",
    "amount": 175.0
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2020-03-31",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "start",
  "timer_started_on": 1585672425,
  "timer_stopped_on": 0,
  "label_ids": [

  ],
  "user_ids": [

  ],
  "updated_at": 1585672425,
  "created_at": 1585672425,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "to": "2020-03-31T22:03:45+02:00",
  "from": "2020-03-31T18:33:45+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": null,
  "updater_id": 28291,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

Stop timer on an event

Request

curl "https://api.timelyapp.com/1.1/12058/events/10843/stop" -d '' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer vswKEewZQ11mSTtwAE-4GWSNTQHsBnc53mPyLxlbw94" \
    -H "Cookie: "

Endpoint

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

PUT /1.1/12058/events/10843/stop
Accept: application/json
Content-Type: application/json
Authorization: Bearer vswKEewZQ11mSTtwAE-4GWSNTQHsBnc53mPyLxlbw94

Parameters

Name Description
id required Event ID

Response

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

{
  "id": 10843,
  "uid": "7596bea4cb46be88876d2a65f23ffd92",
  "user": {
    "id": 28293,
    "email": "marijauowsawfg@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/3ad93209c31ea7d6acc652a7f6ae9d97?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/3ad93209c31ea7d6acc652a7f6ae9d97?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/3ad93209c31ea7d6acc652a7f6ae9d97?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:46+02:00"
  },
  "project": {
    "id": 11212,
    "active": true,
    "account_id": 12058,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672426,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7769,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:46+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 22500,
    "formatted": "$225.00",
    "amount": 225.0
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2020-03-31",
  "note": "Notes for testing with some random #hash in it.",
  "sequence": 1,
  "estimated": false,
  "timer_state": "stop",
  "timer_started_on": 0,
  "timer_stopped_on": 1585672426,
  "label_ids": [

  ],
  "user_ids": [

  ],
  "updated_at": 1585672426,
  "created_at": 1585672426,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "to": "2020-03-31T22:03:46+02:00",
  "from": "2020-03-31T18:33:46+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": null,
  "updater_id": 28293,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

Update an event

Note: Normal users can edit the project_id and events created by other users on their account. Limited users can only edit their own events.

Request

curl "https://api.timelyapp.com/1.1/12059/events/10844" -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 2CtNN1OwIn-Nb-zQyLBhiOljtHB525y9xKFwKw_HWT4" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/events/:id

PUT /1.1/12059/events/10844
Accept: application/json
Content-Type: application/json
Authorization: Bearer 2CtNN1OwIn-Nb-zQyLBhiOljtHB525y9xKFwKw_HWT4

Parameters

{"event":{"note":"Updated notes","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
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

Response

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

{
  "id": 10844,
  "uid": "9697361bd81c04fb4ea891d63104a5a3",
  "user": {
    "id": 28295,
    "email": "marijagyfxoymr@timelyapp.com",
    "name": "Marija Petrovic",
    "avatar": {
      "timeline": "https://www.gravatar.com/avatar/3b9060e0a869f350a1b3396651d57836?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.jpg&s=",
      "medium_retina": "https://www.gravatar.com/avatar/3b9060e0a869f350a1b3396651d57836?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/3b9060e0a869f350a1b3396651d57836?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s="
    },
    "updated_at": "2020-03-31T18:33:46+02:00"
  },
  "project": {
    "id": 11213,
    "active": true,
    "account_id": 12059,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672426,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7770,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:46+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "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": 4,
    "minutes": 0,
    "seconds": 0,
    "formatted": "04:00",
    "total_hours": 4.0,
    "total_seconds": 14400,
    "total_minutes": 240
  },
  "cost": {
    "fractional": 0,
    "formatted": "$0.00",
    "amount": 0.0
  },
  "estimated_cost": {
    "fractional": 20000,
    "formatted": "$200.00",
    "amount": 200.0
  },
  "day": "2020-03-31",
  "note": "Updated notes",
  "sequence": 1,
  "estimated": true,
  "timer_state": "default",
  "timer_started_on": 0,
  "timer_stopped_on": 0,
  "label_ids": [

  ],
  "user_ids": [

  ],
  "updated_at": 1585672426,
  "created_at": 1585672426,
  "created_from": "Web",
  "updated_from": "Timely",
  "billed": false,
  "to": "2020-03-31T22:03:46+02:00",
  "from": "2020-03-31T18:33:46+02:00",
  "deleted": false,
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "creator_id": null,
  "updater_id": 28295,
  "external_id": null,
  "entry_ids": [

  ],
  "suggestion_id": null
}

Labels

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

Create a label

Request

curl "https://api.timelyapp.com/1.1/12069/labels" -d '{"label":{"name":"Web Programming"}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer TxuUFGbzYWjLrbaph1pJheHY_FoCsOlPJp6R7T_n5Po" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/labels

POST /1.1/12069/labels
Accept: application/json
Content-Type: application/json
Authorization: Bearer TxuUFGbzYWjLrbaph1pJheHY_FoCsOlPJp6R7T_n5Po

Parameters

{"label":{"name":"Web Programming"}}
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

Response

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

{
  "id": 5635,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": "https://raw.githubusercontent.com/iamcal/emoji-data/v4.0.4/img-twitter-64/1f3f7-fe0f.png",
  "children": [

  ]
}

Delete a label

Request

curl "https://api.timelyapp.com/1.1/12070/labels/5636" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer o8zeOzNLLlMW84qqoR-F2VMlV_uYFfTsxRF4ksg8VHU" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/labels/:id

DELETE /1.1/12070/labels/5636
Accept: application/json
Content-Type: application/json
Authorization: Bearer o8zeOzNLLlMW84qqoR-F2VMlV_uYFfTsxRF4ksg8VHU

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

Endpoint

GET /1.1/:account_id/labels

GET /1.1/12073/labels?parent_id=5638
Accept: application/json
Content-Type: application/json
Authorization: Bearer Bi89FPnQkOxzEjkRo5Y_PFPeN0SLyUKsbk5ZHnwMAKU

Parameters

parent_id: 5638
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": 5638,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": null,
  "children": [

  ]
}

List all labels

Get all the tags present in user’s account.

Request

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

Endpoint

GET /1.1/:account_id/labels

GET /1.1/12072/labels
Accept: application/json
Content-Type: application/json
Authorization: Bearer JfFsT_h54U-GzB2Q6jVauD22f8uonuxcTByJwNEB5xM

Parameters

None known.

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

Endpoint

GET /1.1/:account_id/labels/:id

GET /1.1/12071/labels/5637
Accept: application/json
Content-Type: application/json
Authorization: Bearer LuCxGQi5SQ6R7aPWEmPaplunRc0dtr-tIMOrVbgl8Ak

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": 5637,
  "name": "Web Programming",
  "sequence": 1,
  "parent_id": null,
  "emoji": null,
  "children": [

  ]
}

Update a label

Request

curl "https://api.timelyapp.com/1.1/12074/labels/5639" -d '{"label":{"name":"updated name"}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 52MdDXIA4iA_6bO7D-ta636r1PZ2BN2acs0_S1O0kXU" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/labels/:id

PUT /1.1/12074/labels/5639
Accept: application/json
Content-Type: application/json
Authorization: Bearer 52MdDXIA4iA_6bO7D-ta636r1PZ2BN2acs0_S1O0kXU

Parameters

{"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

Response

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

{
  "id": 5639,
  "name": "updated name",
  "sequence": 1,
  "parent_id": null,
  "emoji": "https://raw.githubusercontent.com/iamcal/emoji-data/v4.0.4/img-twitter-64/1f3f7-fe0f.png",
  "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/12085/users/current/permissions" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 2iIrNMybbMBHOwEQ1CPxIzGiBDk0i4qvj_AUTF3A1_w" \
    -H "Cookie: "

Endpoint

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

GET /1.1/12085/users/current/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer 2iIrNMybbMBHOwEQ1CPxIzGiBDk0i4qvj_AUTF3A1_w

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": "label",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "project",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "company",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "team",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "account",
    "permissions": [
      "read",
      "update"
    ]
  },
  {
    "resource": "report",
    "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/12086/users/28346/permissions" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Rmaw_uw8B4s-Dxdp1Yj_Ypuuk2oULO8FOI1e9B5WAvk" \
    -H "Cookie: "

Endpoint

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

GET /1.1/12086/users/28346/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer Rmaw_uw8B4s-Dxdp1Yj_Ypuuk2oULO8FOI1e9B5WAvk

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": "label",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "project",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "company",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "team",
    "permissions": [
      "create",
      "read",
      "update",
      "delete"
    ]
  },
  {
    "resource": "account",
    "permissions": [
      "read",
      "update"
    ]
  },
  {
    "resource": "report",
    "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/12092/projects" -d '{"project":{"name":"New Project","rate_type":"project","hour_rate":50.0,"active":true,"deleted":false,"currency_code":"usd","color":"67a3bc","client_id":7794,"budget_type":"M","budget":300,"users":[{"user_id":28358}],"budget_recurrence":{"recur":"week","start_date":"2018-09-21","end_date":"2019-09-21","recur_until":"end_date"},"labels":[{"label_id":5640,"required":true},{"label_id":5641,"required":true},{"label_id":5642,"required":false},{"label_id":5643,"required":false}]}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer oqOEfR3bt-n8LpXa9kiNzlM_g-BW6ANqPcST1VOztoQ" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/projects

POST /1.1/12092/projects
Accept: application/json
Content-Type: application/json
Authorization: Bearer oqOEfR3bt-n8LpXa9kiNzlM_g-BW6ANqPcST1VOztoQ

Parameters

{"project":{"name":"New Project","rate_type":"project","hour_rate":50.0,"active":true,"deleted":false,"currency_code":"usd","color":"67a3bc","client_id":7794,"budget_type":"M","budget":300,"users":[{"user_id":28358}],"budget_recurrence":{"recur":"week","start_date":"2018-09-21","end_date":"2019-09-21","recur_until":"end_date"},"labels":[{"label_id":5640,"required":true},{"label_id":5641,"required":true},{"label_id":5642,"required":false},{"label_id":5643,"required":false}]}}
Name Description
project required Project attributes
name required Specifies the project name
color required Specifies the project color. It should be one of these: 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
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 }]

Response

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

{
  "id": 11238,
  "active": true,
  "account_id": 12092,
  "name": "New Project",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "updated_at": 1585672431,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 7794,
    "name": "Timely",
    "active": true,
    "external_id": null,
    "updated_at": "2020-03-31T18:33:51+02:00"
  },
  "required_notes": false,
  "budget": 300,
  "budget_type": "M",
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "users": [
    {
      "user_id": 28358,
      "hour_rate": 50.0,
      "hour_rate_in_cents": 5000.0,
      "updated_at": "2020-03-31T18:33:51+02:00",
      "created_at": "2020-03-31T18:33:51+02:00",
      "deleted": false
    }
  ],
  "labels": [
    {
      "project_id": 11238,
      "label_id": 5640,
      "budget": null,
      "required": true,
      "updated_at": "2020-03-31T18:33:51+02:00"
    },
    {
      "project_id": 11238,
      "label_id": 5641,
      "budget": null,
      "required": true,
      "updated_at": "2020-03-31T18:33:51+02:00"
    },
    {
      "project_id": 11238,
      "label_id": 5642,
      "budget": null,
      "required": false,
      "updated_at": "2020-03-31T18:33:51+02:00"
    },
    {
      "project_id": 11238,
      "label_id": 5643,
      "budget": null,
      "required": false,
      "updated_at": "2020-03-31T18:33:51+02:00"
    }
  ],
  "label_ids": [
    5640,
    5641,
    5642,
    5643
  ],
  "required_label_ids": [
    5640,
    5641
  ],
  "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": "2020-03-31T18:33:51+02:00"
  }
}

Delete a project

Request

curl "https://api.timelyapp.com/1.1/12093/projects/11239" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer -7EkKZdSwMuIkUezzxlq3yucGm2yZMhDs6ClhHLNWsw" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/projects/:id

DELETE /1.1/12093/projects/11239
Accept: application/json
Content-Type: application/json
Authorization: Bearer -7EkKZdSwMuIkUezzxlq3yucGm2yZMhDs6ClhHLNWsw

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: Normal users can access all projects on an account. Limited users can only access the projects they belong to.

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

Request

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

Endpoint

GET /1.1/:account_id/projects

GET /1.1/12095/projects
Accept: application/json
Content-Type: application/json
Authorization: Bearer yliDIAMJmkQgf3k93oQLnldKkMDIKPVcytAhYTPSOg8

Parameters

Name Description
offset Retrieve projects from offset
limit Retrieve number of projects
order Sorting order on updated_at
filter Filter projects - mine, active, archived, all
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": 11241,
    "active": true,
    "account_id": 12095,
    "name": "Timely",
    "color": "67a3bc",
    "rate_type": "project",
    "billable": true,
    "updated_at": 1585672431,
    "external_id": null,
    "budget_scope": null,
    "client": {
      "id": 7797,
      "name": "Timely",
      "active": true,
      "external_id": null,
      "updated_at": "2020-03-31T18:33:51+02:00"
    },
    "required_notes": false,
    "budget": 0,
    "budget_type": "",
    "hour_rate": 50.0,
    "hour_rate_in_cents": 5000.0,
    "users": [
      {
        "user_id": 28364,
        "hour_rate": 100.0,
        "hour_rate_in_cents": 10000.0,
        "updated_at": "2020-03-31T18:33:51+02:00",
        "created_at": "2020-03-31T18:33:51+02: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/12094/projects/11240" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 2DplHg25qQGLHOo-AxWl_D_-F0-dOEjdbDdQ7FTirv0" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/projects/:id

GET /1.1/12094/projects/11240
Accept: application/json
Content-Type: application/json
Authorization: Bearer 2DplHg25qQGLHOo-AxWl_D_-F0-dOEjdbDdQ7FTirv0

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": 11240,
  "active": true,
  "account_id": 12094,
  "name": "Timely",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "updated_at": 1585672431,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 7796,
    "name": "Timely",
    "active": true,
    "external_id": null,
    "updated_at": "2020-03-31T18:33:51+02:00"
  },
  "required_notes": false,
  "budget": 0,
  "budget_type": "",
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "users": [
    {
      "user_id": 28362,
      "hour_rate": 100.0,
      "hour_rate_in_cents": 10000.0,
      "updated_at": "2020-03-31T18:33:51+02:00",
      "created_at": "2020-03-31T18:33:51+02: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/12097/projects/11243" -d '{"project":{"name":"updated project name"}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer rUqbnINQ53pbK2lcktI8h1bmUk-uXsQyk1kWnZ0rvCk" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/projects/:id

PUT /1.1/12097/projects/11243
Accept: application/json
Content-Type: application/json
Authorization: Bearer rUqbnINQ53pbK2lcktI8h1bmUk-uXsQyk1kWnZ0rvCk

Parameters

{"project":{"name":"updated project name"}}
Name Description
id required Project ID
project Project attributes
name required Specifies the project name
active Example values: “true” or “false”. Using “false” changes the project state to “archived”
color required Specifies the project color. It should be one of these: 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 value
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)
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

Response

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

{
  "id": 11243,
  "active": true,
  "account_id": 12097,
  "name": "updated project name",
  "color": "67a3bc",
  "rate_type": "project",
  "billable": true,
  "updated_at": 1585672432,
  "external_id": null,
  "budget_scope": null,
  "client": {
    "id": 7799,
    "name": "Timely",
    "active": true,
    "external_id": null,
    "updated_at": "2020-03-31T18:33:52+02:00"
  },
  "required_notes": false,
  "budget": 0,
  "budget_type": "",
  "hour_rate": 50.0,
  "hour_rate_in_cents": 5000.0,
  "users": [
    {
      "user_id": 28368,
      "hour_rate": 0.0,
      "hour_rate_in_cents": 0.0,
      "updated_at": "2020-03-31T18:33:52+02:00",
      "created_at": "2020-03-31T18:33:52+02: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

Enjoy clear oversight over your business, including individual and team performance. Export reports in .XLS, .PDF and .CSV formats.

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

Endpoint

POST /1.1/:account_id/reports

POST /1.1/12129/reports
Accept: application/json
Content-Type: application/json
Authorization: Bearer XjXmPsGBfomQLc2ILsVCL9QXZ3AMz-YRG7v47mfNd7I

Parameters

{"user_ids":"28463","since":"2018-01-01","until":"2019-01-01","project_ids":"11312"}
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": 7831,
    "name": "Timely",
    "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
    },
    "cost": {
      "fractional": 25000,
      "formatted": "$250.00",
      "amount": 250.0
    },
    "estimated_cost": {
      "fractional": 40000,
      "formatted": "$400.00",
      "amount": 400.0
    },
    "projects": [
      {
        "id": 11312,
        "active": true,
        "account_id": 12129,
        "name": "Timely",
        "color": "67a3bc",
        "rate_type": "project",
        "billable": true,
        "updated_at": 1585672440,
        "external_id": null,
        "budget_scope": null,
        "client": {
          "id": 7831,
          "name": "Timely",
          "active": true,
          "external_id": null,
          "updated_at": "2020-03-31T18:34:00+02:00"
        },
        "required_notes": false,
        "budget": 0,
        "budget_type": "",
        "hour_rate": 50.0,
        "hour_rate_in_cents": 5000.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
        },
        "cost": {
          "fractional": 25000,
          "formatted": "$250.00",
          "amount": 250.0
        },
        "estimated_cost": {
          "fractional": 40000,
          "formatted": "$400.00",
          "amount": 400.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.com1.1/12130/reports/filter" -d '{"user_ids":"28465","since":"2018-01-01","until":"2019-01-01","project_ids":"11313"}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 0D4ePcYMAAGY3T69zKt68mIhaGGkoLbRTu6_Hu3as4Q" \
    -H "Cookie: "

Endpoint

POST 1.1/:account_id/reports/filter

POST 1.1/12130/reports/filter
Accept: application/json
Content-Type: application/json
Authorization: Bearer 0D4ePcYMAAGY3T69zKt68mIhaGGkoLbRTu6_Hu3as4Q

Parameters

{"user_ids":"28465","since":"2018-01-01","until":"2019-01-01","project_ids":"11313"}
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]

Response

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

{
  "clients": [
    {
      "id": 7832,
      "name": "Timely",
      "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
      },
      "cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.0
      },
      "estimated_cost": {
        "fractional": 40000,
        "formatted": "$400.00",
        "amount": 400.0
      },
      "projects": [
        {
          "id": 11313,
          "active": true,
          "account_id": 12130,
          "name": "Timely",
          "color": "67a3bc",
          "rate_type": "project",
          "billable": true,
          "updated_at": 1585672441,
          "external_id": null,
          "budget_scope": null,
          "client": {
            "id": 7832,
            "name": "Timely",
            "active": true,
            "external_id": null,
            "updated_at": "2020-03-31T18:34:01+02:00"
          },
          "required_notes": false,
          "budget": 0,
          "budget_type": "",
          "hour_rate": 50.0,
          "hour_rate_in_cents": 5000.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
          },
          "cost": {
            "fractional": 25000,
            "formatted": "$250.00",
            "amount": 250.0
          },
          "estimated_cost": {
            "fractional": 40000,
            "formatted": "$400.00",
            "amount": 400.0
          }
        }
      ]
    }
  ],
  "users": [
    {
      "id": 28465,
      "email": "marijaqpikgbnh@timelyapp.com",
      "name": "Marija Petrovic",
      "time_zone": "Europe/Paris",
      "updated_at": 1585672440,
      "active": false,
      "deleted": false,
      "memory_onboarded": true,
      "day_view_onboarded": true,
      "last_received_memories_date": null,
      "default_hour_rate": 0.0,
      "date_format": "dmy",
      "time_format": "24",
      "avatar": {
        "large_retina": "https://www.gravatar.com/avatar/d1c17c04ce6a6b3fd8ba29dc31460d2a?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
        "large": "https://www.gravatar.com/avatar/d1c17c04ce6a6b3fd8ba29dc31460d2a?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=",
        "medium_retina": "https://www.gravatar.com/avatar/d1c17c04ce6a6b3fd8ba29dc31460d2a?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
        "medium": "https://www.gravatar.com/avatar/d1c17c04ce6a6b3fd8ba29dc31460d2a?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=",
        "timeline": "https://www.gravatar.com/avatar/d1c17c04ce6a6b3fd8ba29dc31460d2a?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_timeline-41a3c6144fa6b06eceedb1fa1d82ed1763f24f9b93904044558c64c0e868fbec.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
      },
      "cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.0
      },
      "estimated_cost": {
        "fractional": 40000,
        "formatted": "$400.00",
        "amount": 400.0
      }
    }
  ],
  "labels": [
    {
      "id": 0,
      "name": "Untagged",
      "sequence": -1,
      "parent_id": null,
      "emoji": "https://raw.githubusercontent.com/iamcal/emoji-data/v2.4.4/img-twitter-64/1f3f7.png",
      "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
      },
      "cost": {
        "fractional": 25000,
        "formatted": "$250.00",
        "amount": 250.0
      },
      "estimated_cost": {
        "fractional": 40000,
        "formatted": "$400.00",
        "amount": 400.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
      },
      "cost": {
        "fractional": 12500,
        "formatted": "$125.00",
        "amount": 125.0
      },
      "estimated_cost": {
        "fractional": 20000,
        "formatted": "$200.00",
        "amount": 200.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
      },
      "cost": {
        "fractional": 12500,
        "formatted": "$125.00",
        "amount": 125.0
      },
      "estimated_cost": {
        "fractional": 20000,
        "formatted": "$200.00",
        "amount": 200.0
      }
    }
  ]
}

Teams

The team object shows all teams available on an account.

Create a team

Request

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

Endpoint

POST /1.1/:account_id/teams

POST /1.1/12148/teams
Accept: application/json
Content-Type: application/json
Authorization: Bearer -NohJj043lePUUCqc-LS3uofsyn9eXj-vBidQg3mfgw

Parameters

{"team":{"name":"Timely","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":28501,"lead":true},{"user_id":28503,"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": 843,
  "name": "Timely",
  "color": "67a3bc",
  "emoji": "http://path.to/emoji.png",
  "external_id": null,
  "user_ids": [
    28501,
    28503
  ],
  "users": [
    {
      "id": 1231,
      "user_id": 28501,
      "team_id": 843,
      "lead": true
    },
    {
      "id": 1232,
      "user_id": 28503,
      "team_id": 843,
      "lead": false
    }
  ]
}

Delete a team

Request

curl "https://api.timelyapp.com/1.1/12149/teams/844" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sj4ISxtWpErJ7QmdRgiPXImobATdWKXypZjAzSszcu8" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/teams/:id

DELETE /1.1/12149/teams/844
Accept: application/json
Content-Type: application/json
Authorization: Bearer sj4ISxtWpErJ7QmdRgiPXImobATdWKXypZjAzSszcu8

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

Endpoint

GET /1.1/:account_id/teams

GET /1.1/12151/teams
Accept: application/json
Content-Type: application/json
Authorization: Bearer w8AH0Zs3rkULjZ5mcJ9ixCupJPQqw5nf9km488ZOO74

Parameters

None known.

Response

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

[

]

Retrieve a team

Request

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

Endpoint

GET /1.1/:account_id/teams/:id

GET /1.1/12150/teams/845
Accept: application/json
Content-Type: application/json
Authorization: Bearer DpOj8wIAg3k4UkECBH3hHaOEnXrh7eeXgagyjbBhH90

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
page Page number (Default 1)
per_page Records per page (Default 50)
order Sorting order on name

Response

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

{
  "id": 845,
  "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/12152/teams/846" -d '{"team":{"name":"Backend","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":28510,"lead":true}]}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer t_GwBCf43rIpbV2TAAdhY9NvXWEiAHwtMZ-dXQUIzp8" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/teams/:id

PUT /1.1/12152/teams/846
Accept: application/json
Content-Type: application/json
Authorization: Bearer t_GwBCf43rIpbV2TAAdhY9NvXWEiAHwtMZ-dXQUIzp8

Parameters

{"team":{"name":"Backend","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":28510,"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": 846,
  "name": "Backend",
  "color": "67a3bc",
  "emoji": "http://path.to/emoji.png",
  "external_id": null,
  "user_ids": [
    28510
  ],
  "users": [
    {
      "id": 1233,
      "user_id": 28510,
      "team_id": 846,
      "lead": true
    }
  ]
}

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/12157/users" -d '{"user":{"name":"Marija Petrovic","email":"marija@timely.com","user_level":"normal","admin":false,"projects":[{"project_id":11341,"hour_rate":10}]},"admin":{"id":5709,"email":"notifications@timelyapp.com","created_at":"2020-03-31T18:34:07.000+02:00","updated_at":"2020-03-31T18:34:07.000+02:00","name":"Timely","notifier":false}}' -X POST \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer l3KK_uBmyhPhxTxpCZC-QzBErxVsKIq_0vIYsVjrNHA" \
    -H "Cookie: "

Endpoint

POST /1.1/:account_id/users

POST /1.1/12157/users
Accept: application/json
Content-Type: application/json
Authorization: Bearer l3KK_uBmyhPhxTxpCZC-QzBErxVsKIq_0vIYsVjrNHA

Parameters

{"user":{"name":"Marija Petrovic","email":"marija@timely.com","user_level":"normal","admin":false,"projects":[{"project_id":11341,"hour_rate":10}]},"admin":{"id":5709,"email":"notifications@timelyapp.com","created_at":"2020-03-31T18:34:07.000+02:00","updated_at":"2020-03-31T18:34:07.000+02:00","name":"Timely","notifier":false}}
Name Description
user required Label 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 }]
user_level Specifies the user level; either “normal” or “limited”. The default is "normal". For example: "user_level": "normal"
admin 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)

Response

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

{
  "id": 28522,
  "email": "marija@timely.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": false,
  "memory_onboarded": false,
  "created_at": 1585672447,
  "updated_at": 1585672447,
  "default_hour_rate": 0.0,
  "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-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25"
  },
  "type": "User",
  "user_level": "normal",
  "admin": false,
  "hide_hourly_rate": false,
  "deleted": false
}

Delete a user

Request

curl "https://api.timelyapp.com/1.1/12158/users/28523" -d '' -X DELETE \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 2llWu9OiYUkiqYmYvW4HHT9Mw4i7ZEd5tiZ1dt5JxSk" \
    -H "Cookie: "

Endpoint

DELETE /1.1/:account_id/users/:id

DELETE /1.1/12158/users/28523
Accept: application/json
Content-Type: application/json
Authorization: Bearer 2llWu9OiYUkiqYmYvW4HHT9Mw4i7ZEd5tiZ1dt5JxSk

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/12161/users" -X GET \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer B-tfpv3-T1y4dLRhwiBBEc10GUXEoeEVo2hH5jG67dE" \
    -H "Cookie: "

Endpoint

GET /1.1/:account_id/users

GET /1.1/12161/users
Accept: application/json
Content-Type: application/json
Authorization: Bearer B-tfpv3-T1y4dLRhwiBBEc10GUXEoeEVo2hH5jG67dE

Parameters

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

Response

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

[
  {
    "id": 28529,
    "email": "marijaczqijfpu@timelyapp.com",
    "name": "Marija Petrovic",
    "active": false,
    "day_view_onboarded": true,
    "memory_onboarded": true,
    "created_at": 1585672448,
    "updated_at": 1585672448,
    "default_hour_rate": 0.0,
    "last_received_memories_date": null,
    "sign_in_count": null,
    "external_id": null,
    "time_zone": "Europe/Paris",
    "avatar": {
      "large_retina": "https://www.gravatar.com/avatar/01386cf95ad9c311edd98b7e133b91c8?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
      "large": "https://www.gravatar.com/avatar/01386cf95ad9c311edd98b7e133b91c8?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
      "medium_retina": "https://www.gravatar.com/avatar/01386cf95ad9c311edd98b7e133b91c8?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "medium": "https://www.gravatar.com/avatar/01386cf95ad9c311edd98b7e133b91c8?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
      "small_retina": "https://www.gravatar.com/avatar/01386cf95ad9c311edd98b7e133b91c8?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25",
      "small": "https://www.gravatar.com/avatar/01386cf95ad9c311edd98b7e133b91c8?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25"
    },
    "type": "User",
    "user_level": "normal",
    "admin": true,
    "hide_hourly_rate": false,
    "deleted": false
  }
]

Retrieve a user

Request

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

Endpoint

GET /1.1/:account_id/users/:id

GET /1.1/12159/users/28525
Accept: application/json
Content-Type: application/json
Authorization: Bearer jxSdyAmxnUivUQptm66Xij4RyCJPUn19abVzSvripDA

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": 28525,
  "email": "marijaromkezss@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1585672448,
  "updated_at": 1585672448,
  "default_hour_rate": 0.0,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/86da1ca253fa78e522f4fe32db74b5c0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/86da1ca253fa78e522f4fe32db74b5c0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/86da1ca253fa78e522f4fe32db74b5c0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/86da1ca253fa78e522f4fe32db74b5c0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/86da1ca253fa78e522f4fe32db74b5c0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/86da1ca253fa78e522f4fe32db74b5c0?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25"
  },
  "type": "User",
  "user_level": "normal",
  "admin": true,
  "hide_hourly_rate": false,
  "deleted": false
}

Retrieve current user

Request

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

Endpoint

GET /1.1/:account_id/users/current

GET /1.1/12160/users/current
Accept: application/json
Content-Type: application/json
Authorization: Bearer mtqd0stNdphkuFWiBx6EFlLE6bsWrKtDab89MH09F4M

Parameters

Name Description
account_id The account ID containing the current user

Response

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

{
  "id": 28527,
  "email": "marijakdkglpcg@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1585672448,
  "updated_at": 1585672448,
  "default_hour_rate": 0.0,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/5e1a5fad0d33cde9ab37da4c91af7173?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/5e1a5fad0d33cde9ab37da4c91af7173?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/5e1a5fad0d33cde9ab37da4c91af7173?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/5e1a5fad0d33cde9ab37da4c91af7173?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/5e1a5fad0d33cde9ab37da4c91af7173?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/5e1a5fad0d33cde9ab37da4c91af7173?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25"
  },
  "type": "User",
  "user_level": "normal",
  "admin": true,
  "hide_hourly_rate": false,
  "deleted": false
}

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.

Admins can update other users’ profiles. Limited users can only update their own profile.

Request

curl "https://api.timelyapp.com/1.1/12162/users/28531" -d '{"user":{"name":"Robin","user_level":"normal","admin":false,"projects":[{"project_id":11346,"hour_rate":10}]},"admin":{"id":5714,"email":"notifications@timelyapp.com","created_at":"2020-03-31T18:34:08.000+02:00","updated_at":"2020-03-31T18:34:08.000+02:00","name":"Timely","notifier":false}}' -X PUT \
    -H "Host: api.timelyapp.com" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer eAx1Y2UeoGMi-k-XDffvTfziwUQJNKsjSiaN1iktBQg" \
    -H "Cookie: "

Endpoint

PUT /1.1/:account_id/users/:id

PUT /1.1/12162/users/28531
Accept: application/json
Content-Type: application/json
Authorization: Bearer eAx1Y2UeoGMi-k-XDffvTfziwUQJNKsjSiaN1iktBQg

Parameters

{"user":{"name":"Robin","user_level":"normal","admin":false,"projects":[{"project_id":11346,"hour_rate":10}]},"admin":{"id":5714,"email":"notifications@timelyapp.com","created_at":"2020-03-31T18:34:08.000+02:00","updated_at":"2020-03-31T18:34:08.000+02:00","name":"Timely","notifier":false}}
Name Description
id required the numerical ID of the user
user required Label attributes
name required Specifies the user name
email required Specifies the user email
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_level Specifies the user level; either “normal” or “limited”. The default is "normal". For example: "user_level": "normal"
admin 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)

Response

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

{
  "id": 28531,
  "email": "marijaapchgduc@timelyapp.com",
  "name": "Marija Petrovic",
  "active": false,
  "day_view_onboarded": true,
  "memory_onboarded": true,
  "created_at": 1585672448,
  "updated_at": 1585672448,
  "default_hour_rate": 0.0,
  "last_received_memories_date": null,
  "sign_in_count": null,
  "external_id": null,
  "time_zone": "Europe/Paris",
  "avatar": {
    "large_retina": "https://www.gravatar.com/avatar/c9b2f6082a9f49b7554b900761d97ad3?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
    "large": "https://www.gravatar.com/avatar/c9b2f6082a9f49b7554b900761d97ad3?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_large_retina-d4612e316dfb7aecf35477055a2987158899c94e147efe7e5960d605dc37b674.jpg&s=200",
    "medium_retina": "https://www.gravatar.com/avatar/c9b2f6082a9f49b7554b900761d97ad3?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
    "medium": "https://www.gravatar.com/avatar/c9b2f6082a9f49b7554b900761d97ad3?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_medium_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=50",
    "small_retina": "https://www.gravatar.com/avatar/c9b2f6082a9f49b7554b900761d97ad3?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25",
    "small": "https://www.gravatar.com/avatar/c9b2f6082a9f49b7554b900761d97ad3?d=http%3A%2F%2Fapp.timelyapp.local%2Fassets%2Fthumbs%2Fuser_small_retina-4715ba0edcfabca71404b6c34fa565f9edcd98f3dcea355e3695445ee5a3238b.jpg&s=25"
  },
  "type": "User",
  "user_level": "normal",
  "admin": false,
  "hide_hourly_rate": false,
  "deleted": false
}

Errors

Example responses:

422 Unprocessable Entity

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

422 Unprocessable Entity

403 Forbidden

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

404 Not Found

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

401 Unauthorized

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

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

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

The Timely API uses the following error codes:

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