Introduction
Welcome! This document provides a full list of all Timely APIs currently available, so you can start integrating Timely with your favorite applications.
Got questions? Please send them to support@timelyapp.com.
Authentication
OAuth2 Authentication: http://tools.ietf.org/html/rfc6749
Create an OAuth Application (only available to the Admin User): https://app.timelyapp.com/:account_id/oauth_applications
Enter your application name and the redirect_url to your application.
Acquire the Application Id and Secret.
The base URL for all API's is: https://api.timelyapp.com/1.1
Authorization
OAuth Code
Example Request: (try this in your web browser)
https://api.timelyapp.com/1.1/oauth/authorize?response_type=code
&redirect_uri=your_redirect_uri&client_id=your_client_id
Users are redirected to request their Timely identity.
HTTP Request
GET /oauth/authorize
Compulsory Parameters
| Parameter | Description |
|---|---|
| response_type | code |
| redirect_uri | http://your-redirect-url/ |
| client_id | your_application_id |
If the user accepts your request, Timely will redirect back with the code parameter, which you need to use to get the token.
OAuth Token
Example Request:
curl -X POST --data "redirect_uri=https://your-redirect_url/&code=your_response_code
&client_id=application_id&client_secret=application_secret&grant_type=authorization_code"
https://api.timelyapp.com/1.1/oauth/token
{
"access_token":"1886f011cd72eabc88d087eabd741b51a9059f5ba57c7bc439285fe86a4e465a",
"token_type":"bearer",
"refresh_token":"9db4d1a5d87c707b8125d8f93ad08091fb3ff8b93be901dbeaba968cf532ed9b"
}
200 OK
Users are redirected to request their Timely identity.
HTTP Request
POST /oauth/token
Compulsory Parameters
| Parameter | Description |
|---|---|
| redirect_uri | http://your-redirect-url/ |
| code | your_response_code |
| client_id | your_application_id |
| client_secret | your_application_secret |
| grant_type | authorization_code |
The response will be a token with a refresh token. Use the token to use the following API.
Use Timely API to integrate with your apps
Timely API helps you integrate your application with Timely. Following are the list of API’s available. For any help or support email support@timelyapp.com
Accounts
List all accounts
Returns all the accounts created against one email address.
Request
curl -g "https://api.timelyapp.com/1.1/accounts" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer x_Lj-wEMr3-9lf_O8d1DbJNsA4Fk_vYobVzXyswIb8M" \
-H "Cookie: "
Endpoint
GET /1.1/accounts
GET /1.1/accounts
Accept: application/json
Content-Type: application/json
Authorization: Bearer x_Lj-wEMr3-9lf_O8d1DbJNsA4Fk_vYobVzXyswIb8M
Parameters
None known.
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 365,
"name": "Timely",
"color": "44505e",
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"logo": {
"large_retina": "/assets/account_thumbs/account_large_retina-8bc212c450af14b3a0ea49098cdddbe4f90d5eb5fc57adfeade6ac1ad8fb1d4a.png",
"medium_retina": "/assets/account_thumbs/account_medium_retina-10dfbcc6733ccba1d485971f63c5eb7f9b7ed1a942a0ebd140e292bcb1e4dbea.png",
"small_retina": "/assets/account_thumbs/account_small_retina-ea5df153b4cd96fc801e2361afc7d1b06d7b95ce5c358250b81149e1a20689df.png",
"brand_logo": false
},
"from": "Web",
"max_users": 0,
"seats": 1,
"max_projects": 0,
"plan_id": 364,
"plan_name": "Essential",
"next_charge": "2025-06-13",
"start_of_week": 0,
"created_at": 1747124461,
"payment_mode": "web",
"paid": true,
"company_size": "10-49",
"plan_code": "essential",
"plan_custom": false,
"appstore_transaction_id": null,
"owner_id": 802,
"weekly_user_capacity": 40.0,
"default_work_days": "MON,TUE,WED,THU,FRI",
"default_hour_rate": 0.0,
"support_email": "support@timelyapp.com",
"estimated_company_size": null,
"industry": null,
"memory_retention_days": 0,
"tic_force_enable": false,
"num_users": 1,
"num_projects": 0,
"active_projects_count": 0,
"total_projects_count": 0,
"capacity": {
"hours": 40,
"minutes": 0,
"seconds": 0.0,
"formatted": "40:00",
"total_hours": 40.0,
"total_seconds": 144000.0,
"total_minutes": 2400.0
},
"status": "active",
"beta": false,
"azure_ad_enabled": true,
"expired": false,
"trial": false,
"days_to_end_trial": 0,
"features": [
{
"name": "api_access",
"days": -1
},
{
"name": "control",
"days": -1
},
{
"name": "memories",
"days": -1
},
{
"name": "billing",
"days": -1
},
{
"name": "project_required_fields",
"days": -1
},
{
"name": "teams",
"days": -1
},
{
"name": "recurring_budget",
"days": -1
},
{
"name": "notifications_project_budget",
"days": -1
},
{
"name": "weekly_user_capacity",
"days": -1
},
{
"name": "company_view",
"days": -1
},
{
"name": "anomalies",
"days": -1
},
{
"name": "log_hours_for_others",
"days": -1
},
{
"name": "project_budget",
"days": -1
},
{
"name": "budgets_hourly_rates",
"days": -1
},
{
"name": "account_branding",
"days": -1
},
{
"name": "team_lead",
"days": -1
},
{
"name": "ai_timesheet_creation",
"days": -1
},
{
"name": "in_app_support",
"days": -1
},
{
"name": "people_dashboard",
"days": -1
},
{
"name": "people_notify",
"days": -1
},
{
"name": "premium_integrations",
"days": -1
},
{
"name": "individual_capacity",
"days": -1
},
{
"name": "audits",
"days": -1
},
{
"name": "project_dashboard",
"days": -1
},
{
"name": "high_level_reports",
"days": -1
},
{
"name": "live_reports",
"days": -1
},
{
"name": "invoices",
"days": -1
},
{
"name": "planned_entries",
"days": -1
},
{
"name": "internal_costs",
"days": -1
},
{
"name": "memory_retention",
"days": -1
},
{
"name": "custom_project_currencies",
"days": -1
},
{
"name": "capacity_reports",
"days": -1
},
{
"name": "day_locking",
"days": -1
},
{
"name": "user_custom_properties",
"days": -1
},
{
"name": "tasks",
"days": -1
},
{
"name": "planning",
"days": -1
},
{
"name": "batch_log_planned_time",
"days": -1
},
{
"name": "ai_labels_suggestions",
"days": -1
},
{
"name": "integration_monday",
"days": -1
},
{
"name": "hour_states",
"days": -1
},
{
"name": "tic_integrations",
"days": -1
},
{
"name": "tic_support",
"days": -1
},
{
"name": "import_manager",
"days": -1
},
{
"name": "user_project_distribution",
"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/363/activities" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer RCy5xbpVkqODExN0DbtLXF1BDfDTTffdqiO8bHp5Imk" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/activities
GET /1.1/363/activities
Accept: application/json
Content-Type: application/json
Authorization: Bearer RCy5xbpVkqODExN0DbtLXF1BDfDTTffdqiO8bHp5Imk
Parameters
| Name | Description |
|---|---|
| account_id | The ID of the account you want to retrieve |
| limit | Retrieve a limited number of activities |
| offset | Retrieve activities from offset |
| order | Sorting order on created_at |
| filter | Filter activities by entity_type - Ex: filter=projects |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 84,
"user": {
"id": 797,
"email": "marijafrgkpayc@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:00+02:00"
},
"message": "archived",
"activity_type": "archive_project",
"url": "http://app.timelyapp.local:3002/363/projects/367?type=archived_project",
"updated_at": "2025-05-06T10:21:00+02:00",
"detail": null,
"associated_ids": [],
"entity_type": "Project",
"entity_deleted": false,
"parent_entity_name": "",
"entity": {
"id": 367,
"active": true,
"name": "Timely",
"color": "67a3bc",
"client": {
"id": 200,
"name": "Et error rem suscipit.",
"color": "ff8a65",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:00+02:00"
},
"updated_at": "2025-05-13T10:21:00+02:00"
},
"anomaly": false
},
{
"id": 83,
"user": {
"id": 797,
"email": "marijafrgkpayc@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/13db63140da2bb8d8026d455a14f24d9?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:00+02:00"
},
"message": "50% of budget used",
"activity_type": "project_budget_progress_fifty",
"url": "http://app.timelyapp.local:3002/363/projects/367?type=budget_progress",
"updated_at": "2025-05-13T10:21:00+02:00",
"detail": null,
"associated_ids": [],
"entity_type": "Project",
"entity_deleted": false,
"parent_entity_name": "",
"entity": {
"id": 367,
"active": true,
"name": "Timely",
"color": "67a3bc",
"client": {
"id": 200,
"name": "Et error rem suscipit.",
"color": "ff8a65",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:00+02:00"
},
"updated_at": "2025-05-13T10:21:00+02:00"
},
"anomaly": false
}
]
Retrieve an account
Returns one account object related to one company and one subscription plan.
Request
curl -g "https://api.timelyapp.com/1.1/accounts/364" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer hDSXW2KqQK6yFSK-HlWkprblcFICBzHNCoRbq-haUFc" \
-H "Cookie: "
Endpoint
GET /1.1/accounts/:id
GET /1.1/accounts/364
Accept: application/json
Content-Type: application/json
Authorization: Bearer hDSXW2KqQK6yFSK-HlWkprblcFICBzHNCoRbq-haUFc
Parameters
| Name | Description |
|---|---|
| id | The id of the account to be retrieved |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 364,
"name": "Timely",
"color": "44505e",
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"logo": {
"large_retina": "/assets/account_thumbs/account_large_retina-8bc212c450af14b3a0ea49098cdddbe4f90d5eb5fc57adfeade6ac1ad8fb1d4a.png",
"medium_retina": "/assets/account_thumbs/account_medium_retina-10dfbcc6733ccba1d485971f63c5eb7f9b7ed1a942a0ebd140e292bcb1e4dbea.png",
"small_retina": "/assets/account_thumbs/account_small_retina-ea5df153b4cd96fc801e2361afc7d1b06d7b95ce5c358250b81149e1a20689df.png",
"brand_logo": false
},
"from": "Web",
"max_users": 0,
"seats": 1,
"max_projects": 0,
"plan_id": 363,
"plan_name": "Essential",
"next_charge": "2025-06-13",
"start_of_week": 0,
"created_at": 1747124460,
"payment_mode": "web",
"paid": true,
"company_size": "10-49",
"plan_code": "essential",
"plan_custom": false,
"appstore_transaction_id": null,
"owner_id": 800,
"weekly_user_capacity": 40.0,
"default_work_days": "MON,TUE,WED,THU,FRI",
"default_hour_rate": 0.0,
"support_email": "support@timelyapp.com",
"estimated_company_size": null,
"industry": null,
"memory_retention_days": 0,
"tic_force_enable": false,
"num_users": 1,
"num_projects": 0,
"active_projects_count": 0,
"total_projects_count": 0,
"capacity": {
"hours": 40,
"minutes": 0,
"seconds": 0.0,
"formatted": "40:00",
"total_hours": 40.0,
"total_seconds": 144000.0,
"total_minutes": 2400.0
},
"status": "active",
"beta": false,
"azure_ad_enabled": true,
"expired": false,
"trial": false,
"days_to_end_trial": 0,
"features": [
{
"name": "api_access",
"days": -1
},
{
"name": "control",
"days": -1
},
{
"name": "memories",
"days": -1
},
{
"name": "billing",
"days": -1
},
{
"name": "project_required_fields",
"days": -1
},
{
"name": "teams",
"days": -1
},
{
"name": "recurring_budget",
"days": -1
},
{
"name": "notifications_project_budget",
"days": -1
},
{
"name": "weekly_user_capacity",
"days": -1
},
{
"name": "company_view",
"days": -1
},
{
"name": "anomalies",
"days": -1
},
{
"name": "log_hours_for_others",
"days": -1
},
{
"name": "project_budget",
"days": -1
},
{
"name": "budgets_hourly_rates",
"days": -1
},
{
"name": "account_branding",
"days": -1
},
{
"name": "team_lead",
"days": -1
},
{
"name": "ai_timesheet_creation",
"days": -1
},
{
"name": "in_app_support",
"days": -1
},
{
"name": "people_dashboard",
"days": -1
},
{
"name": "people_notify",
"days": -1
},
{
"name": "premium_integrations",
"days": -1
},
{
"name": "individual_capacity",
"days": -1
},
{
"name": "audits",
"days": -1
},
{
"name": "project_dashboard",
"days": -1
},
{
"name": "high_level_reports",
"days": -1
},
{
"name": "live_reports",
"days": -1
},
{
"name": "invoices",
"days": -1
},
{
"name": "planned_entries",
"days": -1
},
{
"name": "internal_costs",
"days": -1
},
{
"name": "memory_retention",
"days": -1
},
{
"name": "custom_project_currencies",
"days": -1
},
{
"name": "capacity_reports",
"days": -1
},
{
"name": "day_locking",
"days": -1
},
{
"name": "user_custom_properties",
"days": -1
},
{
"name": "tasks",
"days": -1
},
{
"name": "planning",
"days": -1
},
{
"name": "batch_log_planned_time",
"days": -1
},
{
"name": "ai_labels_suggestions",
"days": -1
},
{
"name": "integration_monday",
"days": -1
},
{
"name": "hour_states",
"days": -1
},
{
"name": "tic_integrations",
"days": -1
},
{
"name": "tic_support",
"days": -1
},
{
"name": "import_manager",
"days": -1
},
{
"name": "user_project_distribution",
"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/383/clients" -d '{"name":null,"client":{"name":"Uniq name","active":true,"color":"ffeb3b","external_id":null}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer aoLBSuLpJ7IIFAfDjq8aaRDrDZCkodPS_M-V5jcPdRI" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/clients
POST /1.1/383/clients
Accept: application/json
Content-Type: application/json
Authorization: Bearer aoLBSuLpJ7IIFAfDjq8aaRDrDZCkodPS_M-V5jcPdRI
Parameters
{"name":null,"client":{"name":"Uniq name","active":true,"color":"ffeb3b","external_id":null}}
| Name | Description |
|---|---|
| name required | Specifies the client name |
| active | Example values: "true" or "false". Using "false" changes the client state to "archived" |
| external_id | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
| color | Specifies the client color. Example values: 1976d2, 00796b, 2e7d32, d4e157, ffeb3b, ffb74d, ff8a65, e57373, b72367, 7e57c2 (when omitted, a random color will be used) |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 216,
"name": "Uniq name",
"color": "ffeb3b",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:05+02:00"
}
List all clients
NOTE: By default, client list will return first 10000 clients in alphabetical order. You can also use optional parameters like “limit”, “offset”, “show” and “order” to change the results.
Request
curl -g "https://api.timelyapp.com/1.1/384/clients" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XCDDlsLt-8DS5rxvn8WzW795uPrwIZiZC6d1BsFniCc" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/clients
GET /1.1/384/clients
Accept: application/json
Content-Type: application/json
Authorization: Bearer XCDDlsLt-8DS5rxvn8WzW795uPrwIZiZC6d1BsFniCc
Parameters
| Name | Description |
|---|---|
| account_id | Account ID for the clients you want to retrieve |
| limit | Retrieve number of clients |
| offset | Retrieve clients from offset |
| order | "asc (default)" and "desc" |
| show | Specifies which records to retrieve. The default shows a current account’s active clients (show=active). Example: "show=all" or "show=active" or "show=archived" |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 217,
"name": "Error dignissimos sequi repellat.",
"color": "00796b",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:05+02:00",
"external_references": []
}
]
Show client
Request
curl -g "https://api.timelyapp.com/1.1/386/clients/219" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer lbUsSvYaBT2mv3T7rRw88TlvpgTGC7AA0rvaaZVTdAA" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/clients/:id
GET /1.1/386/clients/219
Accept: application/json
Content-Type: application/json
Authorization: Bearer lbUsSvYaBT2mv3T7rRw88TlvpgTGC7AA0rvaaZVTdAA
Parameters
| Name | Description |
|---|---|
| account_id | Account ID for the client you want to retrieve |
| id | Client ID to retrieve |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 219,
"name": "Et sed tempore enim.",
"color": "2e7d32",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:05+02:00",
"external_references": []
}
Update a client
Update client details just by using a client’s ID.
Request
curl "https://api.timelyapp.com/1.1/388/clients/221" -d '{"name":null,"client":{"name":"Updated name","active":true}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer igLneNdPpeICzK4aiMKcJ83JsAbcGB9498tF04bRn-E" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/clients/:id
PUT /1.1/388/clients/221
Accept: application/json
Content-Type: application/json
Authorization: Bearer igLneNdPpeICzK4aiMKcJ83JsAbcGB9498tF04bRn-E
Parameters
{"name":null,"client":{"name":"Updated name","active":true}}
| Name | Description |
|---|---|
| id required | Client ID |
| name required | Specifies the client name |
| active | Example values: “true” or “false”. Using “false” changes the client state to “archived” |
| external_id | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
| color | Specifies the client color. Example values: 1976d2, 00796b, 2e7d32, d4e157, ffeb3b, ffb74d, ff8a65, e57373, b72367, 7e57c2 (when omitted, the current client color will be used) |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 221,
"name": "Updated name",
"color": "00796b",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:06+02:00"
}
Day locking (Locked Time)
Locked Time helps prevent accidental changes or unauthorized edits, making your time records more trustworthy and dependable. This feature offers you a peace of mind by allowing control over which days, weeks, or months to lock or unlock.
Create a Day locking
This API allow you to lock days for an user.
Request
curl "https://api.timelyapp.com/1.1/389/day_properties" -d '{"day_property":{"user_ids":[855],"dates":["2025-05-13","2025-05-14"],"locked":true}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer gWh8KJhDgu4U2wsn9o1lQJIcPNKO7mYi_qh6d-AP73o" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/day_properties
POST /1.1/389/day_properties
Accept: application/json
Content-Type: application/json
Authorization: Bearer gWh8KJhDgu4U2wsn9o1lQJIcPNKO7mYi_qh6d-AP73o
Parameters
{"day_property":{"user_ids":[855],"dates":["2025-05-13","2025-05-14"],"locked":true}}
| Name | Description |
|---|---|
| user_ids required | Specifies the users for which you want lock days. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861" |
| dates required | Specifies the dates to lock, should separated by a comma. Example: dates="2024-08-24, 2024-08-23" |
| locked | Example values: "true" or "false". Using "false" unlocks the days" |
Response
Content-Type: application/json; charset=utf-8
201 Created
[
{
"id": 5,
"user_id": 855,
"account_id": 389,
"date": "2025-05-13",
"locked": true,
"updated_at": 1747124466,
"created_at": 1747124466
},
{
"id": 6,
"user_id": 855,
"account_id": 389,
"date": "2025-05-14",
"locked": true,
"updated_at": 1747124466,
"created_at": 1747124466
}
]
List all locked dates
Note: 1. If “since” and “until” parameters are not passed, the period will default to the current week.
2. If the “user_ids” parameters is not passed, the default will be current user's manageable users.
Request
curl -g "https://api.timelyapp.com/1.1/390/day_properties" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer nR5lSeq_pty02vw5MRqdKnP7LKla7GOvBIPN0Es9Nus" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/day_properties
GET /1.1/390/day_properties
Accept: application/json
Content-Type: application/json
Authorization: Bearer nR5lSeq_pty02vw5MRqdKnP7LKla7GOvBIPN0Es9Nus
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the locked dates you want to retrieve |
| since | Specifies the start date for returned results. Example: since=2014-08-18 |
| until | Specifies the end date for returned results. Example: upto=2014-08-24 |
| dates | Specifies the dates for returned results, should separated by a comma. Example: dates="2024-08-24, 2024-08-23" |
| user_ids | Specifies the users for which you want results. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861" |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 7,
"user_id": 857,
"account_id": 390,
"date": "2025-05-13",
"locked": true,
"updated_at": 1747124467,
"created_at": 1747124467
},
{
"id": 8,
"user_id": 857,
"account_id": 390,
"date": "2025-05-14",
"locked": true,
"updated_at": 1747124467,
"created_at": 1747124467
}
]
Update Day locking
Update locked time by user_ids OR dates.
Request
curl "https://api.timelyapp.com/1.1/391/day_properties" -d '{"day_property":{"user_ids":[859],"dates":["2025-05-13","2025-05-14"],"locked":false}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer BaB911RdSxBDPRJLV5zyIU4aMZ7HHcf9DOwW18qEMx4" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/day_properties
PUT /1.1/391/day_properties
Accept: application/json
Content-Type: application/json
Authorization: Bearer BaB911RdSxBDPRJLV5zyIU4aMZ7HHcf9DOwW18qEMx4
Parameters
{"day_property":{"user_ids":[859],"dates":["2025-05-13","2025-05-14"],"locked":false}}
| Name | Description |
|---|---|
| user_ids required | Specifies the users for which you want lock days. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861" |
| dates required | Specifies the dates to lock, should separated by a comma. Example: dates="2024-08-24, 2024-08-23" |
| locked | Example values: "true" or "false". Using "false" unlocks the days" |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 9,
"user_id": 859,
"account_id": 391,
"date": "2025-05-13",
"locked": false,
"updated_at": 1747124467,
"created_at": 1747124467
},
{
"id": 10,
"user_id": 859,
"account_id": 391,
"date": "2025-05-14",
"locked": false,
"updated_at": 1747124467,
"created_at": 1747124467
}
]
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/410/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-05-13T08:21:10.088Z","to":"2025-05-13T11:51:10.088Z","day":"2025-05-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":397}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer iuzBaPXcXpwtrn3rqm0S5c6tj6_jaFLhEV-jSYxZWE0" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/events
POST /1.1/410/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer iuzBaPXcXpwtrn3rqm0S5c6tj6_jaFLhEV-jSYxZWE0
Parameters
{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-05-13T08:21:10.088Z","to":"2025-05-13T11:51:10.088Z","day":"2025-05-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":397}}
| Name | Description |
|---|---|
| user_id | The numerical ID for the user who the event is created for. Note: the default value is the user_id connected to the API token. Example value: 123 |
| day required | Event day |
| hours required | Event hours |
| minutes required | Event minutes |
| estimated_minutes | Specifies estimated minutes for an event. Example values: 0-60 |
| estimated_hours | Specifies estimated hours for an event. Example values: 0-12 |
| note | Specifies notes for an event |
| from | Specifies the “from” time in a timestamp. Example values: from: "2017-05-26T10:00:00+05:30" |
| to | Specifies the “to” time in a timestamp. Example values: to: "2017-05-26T12:00:00+05:30" |
| label_ids | Specifies label IDs for an event. Example values: label_ids:[2,3,4] |
| project_id | Specifies the project ID for an event |
| external_id | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
Response
Content-Type: application/json; charset=utf-8
201 Created
{
"id": 313,
"uid": "158f3069a435b314a80bdcb024f8e422",
"user": {
"id": 897,
"email": "marijatjvkauuj@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/ef10c2d6cf42698cdbd420bec556c934?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/ef10c2d6cf42698cdbd420bec556c934?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/ef10c2d6cf42698cdbd420bec556c934?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/ef10c2d6cf42698cdbd420bec556c934?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/ef10c2d6cf42698cdbd420bec556c934?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:09+02:00"
},
"project": {
"id": 397,
"active": true,
"account_id": 410,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124470,
"updated_at": 1747124470,
"external_id": null,
"budget_scope": null,
"client": {
"id": 231,
"name": "Enim est est illo.",
"color": "ff8a65",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:10+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 3,
"minutes": 30,
"seconds": 0,
"formatted": "03:30",
"total_hours": 3.5,
"total_seconds": 12600,
"total_minutes": 210
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 35000,
"formatted": "$350.00",
"amount": 350.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124470,
"created_at": 1747124470,
"created_from": "Timely",
"updated_from": "Timely",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:10+02:00",
"from": "2025-05-13T10:21:10+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": 897,
"updater_id": 897,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
Create an event for a project
Request
curl "https://api.timelyapp.com/1.1/409/projects/396/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-05-13T08:21:09.745Z","to":"2025-05-13T11:51:09.745Z","day":"2025-05-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":396}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer VmDBSsE9MDwCArJlJmYFT8fK6jrBL_b41K1Cb4WF3Es" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/projects/:project_id/events
POST /1.1/409/projects/396/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer VmDBSsE9MDwCArJlJmYFT8fK6jrBL_b41K1Cb4WF3Es
Parameters
{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-05-13T08:21:09.745Z","to":"2025-05-13T11:51:09.745Z","day":"2025-05-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","project_id":396}}
| Name | Description |
|---|---|
| user_id | The numerical ID for the user who the event is created for. Note: the default value is the user_id connected to the API token. Example value: 123 |
| day required | Event day |
| hours required | Event hours |
| minutes required | Event minutes |
| project_id required | The numerical ID of the desired project. Example values: 123 |
Response
Content-Type: application/json; charset=utf-8
201 Created
{
"id": 312,
"uid": "950a4152c2b4aa3ad78bdd6b366cc179",
"user": {
"id": 895,
"email": "marijaqiripijb@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/e9de8796a7b12fbf2bce742535ebad89?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/e9de8796a7b12fbf2bce742535ebad89?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/e9de8796a7b12fbf2bce742535ebad89?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/e9de8796a7b12fbf2bce742535ebad89?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/e9de8796a7b12fbf2bce742535ebad89?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:09+02:00"
},
"project": {
"id": 396,
"active": true,
"account_id": 409,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124469,
"updated_at": 1747124469,
"external_id": null,
"budget_scope": null,
"client": {
"id": 230,
"name": "Consequuntur totam maiores ex.",
"color": "1976d2",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:09+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 3,
"minutes": 30,
"seconds": 0,
"formatted": "03:30",
"total_hours": 3.5,
"total_seconds": 12600,
"total_minutes": 210
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 35000,
"formatted": "$350.00",
"amount": 350.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124469,
"created_at": 1747124469,
"created_from": "Timely",
"updated_from": "Timely",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:09+02:00",
"from": "2025-05-13T10:21:09+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": 895,
"updater_id": 895,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
Create an event for another user
Note: Normal users can add hours for any user. If a project_id is not provided, the event is created against a user’s first active project, or the project they logged an event to in the last hour.
Request
curl "https://api.timelyapp.com/1.1/408/users/893/events" -d '{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-05-13T08:21:09.423Z","to":"2025-05-13T11:51:09.423Z","day":"2025-05-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":893}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer HztZFM0d_rd0iWbpQyv3ebsRzWZUM01sp4qUyZkcXjk" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/users/:user_id/events
POST /1.1/408/users/893/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer HztZFM0d_rd0iWbpQyv3ebsRzWZUM01sp4qUyZkcXjk
Parameters
{"event":{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-05-13T08:21:09.423Z","to":"2025-05-13T11:51:09.423Z","day":"2025-05-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":893}}
| Name | Description |
|---|---|
| user_id required | The numerical ID for the user who the event is created for. Note: the default value is the user_id connected to the API token. Example value: 123 |
| day required | Event day |
| hours required | Event hours |
| minutes required | Event minutes |
Response
Content-Type: application/json; charset=utf-8
201 Created
{
"id": 311,
"uid": "9dfcd5e558dfa04aaf37f137a1d9d3e5",
"user": {
"id": 893,
"email": "marijawhtafflv@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/9988ef70166796d876083c73cb09c168?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/9988ef70166796d876083c73cb09c168?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/9988ef70166796d876083c73cb09c168?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/9988ef70166796d876083c73cb09c168?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/9988ef70166796d876083c73cb09c168?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:09+02:00"
},
"project": {
"id": 395,
"active": true,
"account_id": 408,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124469,
"updated_at": 1747124469,
"external_id": null,
"budget_scope": null,
"client": {
"id": 229,
"name": "Aut illo consectetur aperiam.",
"color": "b72367",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:09+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 3,
"minutes": 30,
"seconds": 0,
"formatted": "03:30",
"total_hours": 3.5,
"total_seconds": 12600,
"total_minutes": 210
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 35000,
"formatted": "$350.00",
"amount": 350.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124469,
"created_at": 1747124469,
"created_from": "Timely",
"updated_from": "Timely",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:09+02:00",
"from": "2025-05-13T10:21:09+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": 893,
"updater_id": 893,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
Create bulk events
Note: Use the same list of sub-parameters inside your "create" parameter as specified on Create an event. You can create up to 100 events at a time.
Request
curl "https://api.timelyapp.com/1.1/407/bulk/events" -d '{"create":[{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-05-13T08:21:09.104Z","to":"2025-05-13T11:51:09.104Z","day":"2025-05-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":891,"account_id":407,"project_id":394}]}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ZeROPVEWzwTowPBCEQVWMusHmaXsofWEakN8c91DhYQ" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/bulk/events
POST /1.1/407/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer ZeROPVEWzwTowPBCEQVWMusHmaXsofWEakN8c91DhYQ
Parameters
{"create":[{"hours":3,"minutes":30,"seconds":0,"estimated_hours":4,"estimated_minutes":0,"from":"2025-05-13T08:21:09.104Z","to":"2025-05-13T11:51:09.104Z","day":"2025-05-13","note":"Notes for testing with some random #hash in it.","hour_rate":100,"internal_hour_rate":150,"timer_state":0,"created_from":"Web","updated_from":"Web","user_id":891,"account_id":407,"project_id":394}]}
| Name | Description |
|---|---|
| create | Specifies the parameters for creating a group of events. Example: [{ "hours": 3, "minutes": 30, "seconds": 0, "estimated_hours": 4, "estimated_minutes": 0, "from": "2021-03-04T11:33:36.570+01:00", "to": "2021-03-04T15:03:36.570+01:00", "day": "2021-03-04", "note": "Describe what you worked on here!", "hour_rate": 100, "timer_state": 0, "billed": true, "user_id": 1616, "account_id": 651, "project_id": 620}] |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"deleted_ids": [],
"created_ids": [
310
],
"updated_ids": [],
"errors": {
"create": [],
"update": [],
"delete": []
},
"job": null
}
Delete an event
Note: Normal users can delete events logged to other projects by other users on an account. Limited users can only delete their own events.
Request
curl "https://api.timelyapp.com/1.1/412/events/315" -d '' -X DELETE \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer e6EyOht1eMNxBfVTYa0oXtFnZgos90fnOhWjKwEqFvA" \
-H "Cookie: "
Endpoint
DELETE /1.1/:account_id/events/:id
DELETE /1.1/412/events/315
Accept: application/json
Content-Type: application/json
Authorization: Bearer e6EyOht1eMNxBfVTYa0oXtFnZgos90fnOhWjKwEqFvA
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the hour you want to delete |
| id required | The ID for the hour you want to delete |
Response
Content-Type: application/json; charset=utf-8
200 OK
{}
Delete bulk events
Note: You can delete up to 100 events at a time.
Request
curl "https://api.timelyapp.com/1.1/411/bulk/events" -d '{"delete":[314]}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 2PdTvwbD7zVwOzKy3l9Kw_1WBh-ovknSwO5oft24jY0" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/bulk/events
POST /1.1/411/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer 2PdTvwbD7zVwOzKy3l9Kw_1WBh-ovknSwO5oft24jY0
Parameters
{"delete":[314]}
| Name | Description |
|---|---|
| delete | Specifies the parameters for deleting a group of events. Example: [ 320, 333 ] |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"deleted_ids": [
314
],
"created_ids": [],
"updated_ids": [],
"errors": {
"create": [],
"update": [],
"delete": []
},
"job": null
}
List all events
Get all events linked to active projects on a user’s account.
Note: By default, the API retrieves events from the current date (date of access). To specify a different time range, you need to provide both the “since” and “upto” parameters.
Request
curl -g "https://api.timelyapp.com/1.1/417/events" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 8O7DTdH9RbRK8XSHwCbTxRkCrb1OyBXzpTDMG3qQjak" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/events
GET /1.1/417/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer 8O7DTdH9RbRK8XSHwCbTxRkCrb1OyBXzpTDMG3qQjak
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the hours you want to retrieve. |
| day | Specifies the date for returned events. (Default "current date") Example: day=2014-08-24 |
| since | Specifies the start date for returned results. Example: since=2014-08-18 |
| upto | Specifies the end date for returned results. Example: upto=2014-08-24 |
| filter | Specifies which events to retrieve - logged, all (Default logged) |
| sort | Field to sort events by - updated_at, id, day (Default updated_at) |
| order | Order to retrieve records - desc, asc (Default desc) |
| per_page | Records per page (Default 100) |
| page | Page number (Default 1) |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 320,
"uid": "320722549d1751cf3f247855f937b982",
"user": {
"id": 911,
"email": "marijattdcybgx@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/e02ebd63b33d46aa82a5d18614e9d24b?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/e02ebd63b33d46aa82a5d18614e9d24b?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/e02ebd63b33d46aa82a5d18614e9d24b?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/e02ebd63b33d46aa82a5d18614e9d24b?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/e02ebd63b33d46aa82a5d18614e9d24b?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:11+02:00"
},
"project": {
"id": 404,
"active": true,
"account_id": 417,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124472,
"updated_at": 1747124472,
"external_id": null,
"budget_scope": null,
"client": {
"id": 238,
"name": "Et repudiandae voluptas quibusdam.",
"color": "7e57c2",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:12+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 3,
"minutes": 30,
"seconds": 0,
"formatted": "03:30",
"total_hours": 3.5,
"total_seconds": 12600,
"total_minutes": 210
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 35000,
"formatted": "$350.00",
"amount": 350.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124472,
"created_at": 1747124472,
"created_from": "Web",
"updated_from": "Web",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:12+02:00",
"from": "2025-05-13T10:21:12+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": null,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
]
List all events for a project
Note: By default, the API retrieves events from the current date (date of access). To specify a different time range, you need to provide both the “since” and “upto” parameters.
Request
curl -g "https://api.timelyapp.com/1.1/420/projects/407/events" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer v6BuckP83DI3QOCCsMrsCUIzdRQBrUPSUqL13ijWBY4" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/projects/:project_id/events
GET /1.1/420/projects/407/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer v6BuckP83DI3QOCCsMrsCUIzdRQBrUPSUqL13ijWBY4
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the hours you want to retrieve |
| project_id | The project ID for the hours you want to retrieve |
| day | Specifies the date for returned events. (Default "current date") Example: day=2014-08-24 |
| since | Specifies the start date for returned results. Example: since=2014-08-18 |
| upto | Specifies the end date for returned results. Example: upto=2014-08-24 |
| sort | Field to sort events by - updated_at, id, day (Default updated_at) |
| order | Order to retrieve records - desc, asc (Default desc) |
| per_page | Records per page (Default 100) |
| page | Page number (Default 1) |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 323,
"uid": "bc6dc48b743dc5d013b1abaebd2faed2",
"user": {
"id": 917,
"email": "marijayzpkfiva@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/8f3e50b4c2bea48edef81846db216786?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/8f3e50b4c2bea48edef81846db216786?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/8f3e50b4c2bea48edef81846db216786?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/8f3e50b4c2bea48edef81846db216786?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/8f3e50b4c2bea48edef81846db216786?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:12+02:00"
},
"project": {
"id": 407,
"active": true,
"account_id": 420,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124473,
"updated_at": 1747124473,
"external_id": null,
"budget_scope": null,
"client": {
"id": 241,
"name": "Ratione placeat iusto totam.",
"color": "ff8a65",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:13+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 3,
"minutes": 30,
"seconds": 0,
"formatted": "03:30",
"total_hours": 3.5,
"total_seconds": 12600,
"total_minutes": 210
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 35000,
"formatted": "$350.00",
"amount": 350.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124473,
"created_at": 1747124473,
"created_from": "Web",
"updated_from": "Web",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:13+02:00",
"from": "2025-05-13T10:21:13+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": null,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
]
List all events for a user
Note: By default, the API retrieves events from the current date (date of access). To specify a different time range, you need to provide both the “since” and “upto” parameters.
Request
curl -g "https://api.timelyapp.com/1.1/419/users/915/events" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer A0sXuJ8ZmVzZomPDCl6EyCswWHpHyw-5nI0sjfV04NY" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/users/:user_id/events
GET /1.1/419/users/915/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer A0sXuJ8ZmVzZomPDCl6EyCswWHpHyw-5nI0sjfV04NY
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the hours you want to retrieve |
| user_id | The user ID for the hours you want to retrieve |
| day | Specifies the date for returned events. (Default "current date") Example: day=2014-08-24 |
| since | Specifies the start date for returned results. Example: since=2014-08-18 |
| upto | Specifies the end date for returned results. Example: upto=2014-08-24 |
| sort | Field to sort events by - updated_at, id, day (Default updated_at) |
| order | Order to retrieve records - desc, asc (Default desc) |
| per_page | Records per page (Default 100) |
| page | Page number (Default 1) |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 322,
"uid": "5737c6ec2e0716f3d8a7a5c4e0de0d9a",
"user": {
"id": 915,
"email": "marijangpzhdop@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/c247912a2a27f2cbafb97bc07b790f25?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/c247912a2a27f2cbafb97bc07b790f25?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/c247912a2a27f2cbafb97bc07b790f25?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/c247912a2a27f2cbafb97bc07b790f25?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/c247912a2a27f2cbafb97bc07b790f25?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:12+02:00"
},
"project": {
"id": 406,
"active": true,
"account_id": 419,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124472,
"updated_at": 1747124472,
"external_id": null,
"budget_scope": null,
"client": {
"id": 240,
"name": "Ducimus accusantium libero architecto.",
"color": "ffb74d",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:12+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 3,
"minutes": 30,
"seconds": 0,
"formatted": "03:30",
"total_hours": 3.5,
"total_seconds": 12600,
"total_minutes": 210
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 35000,
"formatted": "$350.00",
"amount": 350.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124472,
"created_at": 1747124472,
"created_from": "Web",
"updated_from": "Web",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:12+02:00",
"from": "2025-05-13T10:21:12+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": null,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
]
Logged in user updating details and user of an event
Request
curl "https://api.timelyapp.com/1.1/428/users/933/events/331" -d '{"event":{"note":"Updated details and project","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer nEvwNJ6hnR-Dy5cUlho81VCQoMEG7YKjupGaPBHMYMU" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/users/:user_id/events/:id
PUT /1.1/428/users/933/events/331
Accept: application/json
Content-Type: application/json
Authorization: Bearer nEvwNJ6hnR-Dy5cUlho81VCQoMEG7YKjupGaPBHMYMU
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": 331,
"uid": "6da37dd3139aa4d9aa55b8d237ec5d4a",
"user": {
"id": 933,
"email": "marijaczohsqey@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/d00976b52d9e4650a5e739ee873806b6?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/d00976b52d9e4650a5e739ee873806b6?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/d00976b52d9e4650a5e739ee873806b6?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/d00976b52d9e4650a5e739ee873806b6?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/d00976b52d9e4650a5e739ee873806b6?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:15+02:00"
},
"project": {
"id": 415,
"active": true,
"account_id": 428,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124475,
"updated_at": 1747124475,
"external_id": null,
"budget_scope": null,
"client": {
"id": 249,
"name": "Fuga libero iusto eum.",
"color": "2e7d32",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:15+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"estimated_duration": {
"hours": 2,
"minutes": 0,
"seconds": 0,
"formatted": "02:00",
"total_hours": 2.0,
"total_seconds": 7200,
"total_minutes": 120
},
"cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 20000,
"formatted": "$200.00",
"amount": 200.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Updated details and project",
"sequence": 1,
"estimated": true,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124475,
"created_at": 1747124475,
"created_from": "Web",
"updated_from": "Timely",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:15+02:00",
"from": "2025-05-13T10:21:15+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": 933,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
Loggedin user updating details and project of their event
Request
curl "https://api.timelyapp.com/1.1/427/projects/414/events/330" -d '{"event":{"note":"Updated details and project","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer R6EDP2qYNvnQMgn-CgrFAm6ubto0mDctmuplHjffJLE" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/projects/:project_id/events/:id
PUT /1.1/427/projects/414/events/330
Accept: application/json
Content-Type: application/json
Authorization: Bearer R6EDP2qYNvnQMgn-CgrFAm6ubto0mDctmuplHjffJLE
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": 330,
"uid": "fe73f687e5bc5280214e0486b273a5f9",
"user": {
"id": 931,
"email": "marijanalbcvdj@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/0c773a2f597f6c5e277d8a18d7ea68ba?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/0c773a2f597f6c5e277d8a18d7ea68ba?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/0c773a2f597f6c5e277d8a18d7ea68ba?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/0c773a2f597f6c5e277d8a18d7ea68ba?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/0c773a2f597f6c5e277d8a18d7ea68ba?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:15+02:00"
},
"project": {
"id": 414,
"active": true,
"account_id": 427,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124475,
"updated_at": 1747124475,
"external_id": null,
"budget_scope": null,
"client": {
"id": 248,
"name": "Tempora quis et earum.",
"color": "ff8a65",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:15+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"estimated_duration": {
"hours": 2,
"minutes": 0,
"seconds": 0,
"formatted": "02:00",
"total_hours": 2.0,
"total_seconds": 7200,
"total_minutes": 120
},
"cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 20000,
"formatted": "$200.00",
"amount": 200.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Updated details and project",
"sequence": 1,
"estimated": true,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124475,
"created_at": 1747124475,
"created_from": "Web",
"updated_from": "Timely",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:15+02:00",
"from": "2025-05-13T10:21:15+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": 931,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
Retrieve an event
Request
curl -g "https://api.timelyapp.com/1.1/415/events/318" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer UpZIeVC89bAjnfTv7IoljMwnLXQVmlPbtOESjxMSuFM" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/events/:id
GET /1.1/415/events/318
Accept: application/json
Content-Type: application/json
Authorization: Bearer UpZIeVC89bAjnfTv7IoljMwnLXQVmlPbtOESjxMSuFM
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": 318,
"uid": "432aca3a1e345e339f35a30c8f65edce",
"user": {
"id": 907,
"email": "marijaxlyuncmh@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/62229d41369de57302421abc3e872819?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/62229d41369de57302421abc3e872819?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/62229d41369de57302421abc3e872819?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/62229d41369de57302421abc3e872819?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/62229d41369de57302421abc3e872819?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:11+02:00"
},
"project": {
"id": 402,
"active": true,
"account_id": 415,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124471,
"updated_at": 1747124471,
"external_id": null,
"budget_scope": null,
"client": {
"id": 236,
"name": "Ut dolor beatae omnis.",
"color": "00796b",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:11+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 3,
"minutes": 30,
"seconds": 0,
"formatted": "03:30",
"total_hours": 3.5,
"total_seconds": 12600,
"total_minutes": 210
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 35000,
"formatted": "$350.00",
"amount": 350.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124471,
"created_at": 1747124471,
"created_from": "Web",
"updated_from": "Web",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:11+02:00",
"from": "2025-05-13T10:21:11+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": null,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
Start timer on an event
Request
curl "https://api.timelyapp.com/1.1/421/events/324/start" -d '' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XuzrUwCov1mCRlOa0v_LXlo0boCh8yU-r1k3zfWc-pU" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/events/:id/start
PUT /1.1/421/events/324/start
Accept: application/json
Content-Type: application/json
Authorization: Bearer XuzrUwCov1mCRlOa0v_LXlo0boCh8yU-r1k3zfWc-pU
Parameters
| Name | Description |
|---|---|
| id required | Event ID |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 324,
"uid": "f2fc990265c712c49d51a18a32b39f0c",
"user": {
"id": 919,
"email": "marijadsxcpkkt@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/1581693b5a2fd12364684c97e1f19d0e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/1581693b5a2fd12364684c97e1f19d0e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/1581693b5a2fd12364684c97e1f19d0e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/1581693b5a2fd12364684c97e1f19d0e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/1581693b5a2fd12364684c97e1f19d0e?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:13+02:00"
},
"project": {
"id": 408,
"active": true,
"account_id": 421,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124473,
"updated_at": 1747124473,
"external_id": null,
"budget_scope": null,
"client": {
"id": 242,
"name": "Eos consequatur molestiae quia.",
"color": "d4e157",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:13+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 3,
"minutes": 30,
"seconds": 0,
"formatted": "03:30",
"total_hours": 3.5,
"total_seconds": 12600,
"total_minutes": 210
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 35000,
"formatted": "$350.00",
"amount": 350.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "start",
"timer_started_on": 1747124473,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124473,
"created_at": 1747124473,
"created_from": "Web",
"updated_from": "Timely",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:13+02:00",
"from": "2025-05-13T10:21:13+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": 919,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [
{
"id": 28,
"hour_id": 324,
"from": "2025-05-13T06:51:13+02:00",
"to": "2025-05-13T10:21:13+02:00",
"entry_ids": []
}
],
"state": null,
"external_links": []
}
Stop timer on an event
Request
curl "https://api.timelyapp.com/1.1/422/events/325/stop" -d '' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 5tXVYpaktR8ARRXpb77WBz-cB5-sVSvceFi8PyVvAIs" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/events/:id/stop
PUT /1.1/422/events/325/stop
Accept: application/json
Content-Type: application/json
Authorization: Bearer 5tXVYpaktR8ARRXpb77WBz-cB5-sVSvceFi8PyVvAIs
Parameters
| Name | Description |
|---|---|
| id required | Event ID |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 325,
"uid": "89f0fd5c927d466d6ec9a21b9ac34ffa",
"user": {
"id": 921,
"email": "marijakdxsntok@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/2170b202d4642436309e458e8bdfb0a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/2170b202d4642436309e458e8bdfb0a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/2170b202d4642436309e458e8bdfb0a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/2170b202d4642436309e458e8bdfb0a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/2170b202d4642436309e458e8bdfb0a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:13+02:00"
},
"project": {
"id": 409,
"active": true,
"account_id": 422,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124473,
"updated_at": 1747124473,
"external_id": null,
"budget_scope": null,
"client": {
"id": 243,
"name": "Eos rerum atque placeat.",
"color": "e57373",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:13+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 4,
"minutes": 30,
"seconds": 0,
"formatted": "04:30",
"total_hours": 4.5,
"total_seconds": 16200,
"total_minutes": 270
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"cost": {
"fractional": 45000,
"formatted": "$450.00",
"amount": 450.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Notes for testing with some random #hash in it.",
"sequence": 1,
"estimated": false,
"timer_state": "stop",
"timer_started_on": 0,
"timer_stopped_on": 1747124473,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124473,
"created_at": 1747124473,
"created_from": "Web",
"updated_from": "Timely",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:13+02:00",
"from": "2025-05-13T10:21:13+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": 921,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
Update an event
Request
curl "https://api.timelyapp.com/1.1/426/events/329" -d '{"event":{"note":"Updated notes","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer zXJtjd9--o619KqKLNFSgAQYrv4EtlmdwR3aazM1fuk" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/events/:id
PUT /1.1/426/events/329
Accept: application/json
Content-Type: application/json
Authorization: Bearer zXJtjd9--o619KqKLNFSgAQYrv4EtlmdwR3aazM1fuk
Parameters
{"event":{"note":"Updated notes","minutes":0,"hours":0,"estimated":true,"estimated_minutes":0,"estimated_hours":2}}
| Name | Description |
|---|---|
| user_id | The numerical ID for the user who the event is updated for. Note: the default value is the user_id connected to the API token. Example value: 123 |
| id required | Event ID |
| day required | Event day |
| hours required | Event hours |
| minutes required | Event minutes |
| project_id | Project ID |
| estimated_minutes | Specifies estimated minutes for an event. Example values: 0-60 |
| estimated_hours | Specifies estimated hours for an event. Example values: 0-12 |
| note | Specifies notes for an event |
| from | Specifies the “from” time in a timestamp. Example values: from: "2017-05-26T10:00:00+05:30" |
| to | Specifies the “to” time in a timestamp. Example values: to: "2017-05-26T12:00:00+05:30" |
| label_ids | Specifies label IDs for an event. Example values: label_ids:[2,3,4] |
| external_id | The external_id can be used to reference external resource ids to Timely resources, should be alphanumeric 512 characters |
| billed | Specifies whether you want an event to be marked as billed. For example: 'billed': false or 'billed': true |
| billable | Specifies whether you want an event to be billable or non-billable. For example: 'billable': false or 'billable': true |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 329,
"uid": "6faa8040da20ef399b63a72d0e4ab575",
"user": {
"id": 929,
"email": "marijapjuocsyg@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/e6093fbd812b10a7c17cb0fafd69495c?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/e6093fbd812b10a7c17cb0fafd69495c?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/e6093fbd812b10a7c17cb0fafd69495c?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/e6093fbd812b10a7c17cb0fafd69495c?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/e6093fbd812b10a7c17cb0fafd69495c?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:14+02:00"
},
"project": {
"id": 413,
"active": true,
"account_id": 426,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124475,
"updated_at": 1747124475,
"external_id": null,
"budget_scope": null,
"client": {
"id": 247,
"name": "Molestiae in et est.",
"color": "b72367",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:15+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"created_from": "Web"
},
"duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"estimated_duration": {
"hours": 2,
"minutes": 0,
"seconds": 0,
"formatted": "02:00",
"total_hours": 2.0,
"total_seconds": 7200,
"total_minutes": 120
},
"cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 20000,
"formatted": "$200.00",
"amount": 200.0,
"currency_code": "usd"
},
"day": "2025-05-13",
"note": "Updated notes",
"sequence": 1,
"estimated": true,
"timer_state": "default",
"timer_started_on": 0,
"timer_stopped_on": 0,
"label_ids": [],
"user_ids": [],
"updated_at": 1747124475,
"created_at": 1747124475,
"created_from": "Web",
"updated_from": "Timely",
"billed": false,
"billable": true,
"to": "2025-05-13T13:51:15+02:00",
"from": "2025-05-13T10:21:15+02:00",
"deleted": false,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000,
"creator_id": null,
"updater_id": 929,
"external_id": null,
"entry_ids": [],
"suggestion_id": null,
"draft": false,
"manage": true,
"forecast_id": null,
"billed_at": null,
"external_link_ids": [],
"internal_cost": {},
"estimated_internal_cost": {},
"internal_cost_rate": 0,
"profit": 0,
"profitability": 0,
"locked_reason": null,
"locked": false,
"invoice_id": null,
"timestamps": [],
"state": null,
"external_links": []
}
Update bulk events
Note: Use the same list of sub-parameters inside your "update" parameter as specified on Update an event. You can update up to 100 events at a time.
Request
curl "https://api.timelyapp.com/1.1/423/bulk/events" -d '{"update":[{"id":326,"note":"updated","billed":true}]}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Ov3QRTPFwEMh_Tppa9alm7pzKMe_DN0DqgXdt-sGYe8" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/bulk/events
POST /1.1/423/bulk/events
Accept: application/json
Content-Type: application/json
Authorization: Bearer Ov3QRTPFwEMh_Tppa9alm7pzKMe_DN0DqgXdt-sGYe8
Parameters
{"update":[{"id":326,"note":"updated","billed":true}]}
| Name | Description |
|---|---|
| update | Specifies the parameters for updating a group of events. Example: [{ "id": 1055, "note": "updated", "billed": true }] |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"deleted_ids": [],
"created_ids": [],
"updated_ids": [
326
],
"errors": {
"create": [],
"update": [],
"delete": []
},
"job": null
}
Forecasts (Tasks)
Forecasts (Tasks) lets you visualize upcoming work for all Timely users in one clean calendar view. You can then quickly assign work or edit plans across your different projects and teams.
Create a forecast
Request
curl "https://api.timelyapp.com/1.1/460/forecasts" -d '{"forecast":{"from":"2022-05-10","to":"2022-05-16","estimated_minutes":150,"users":[{"id":996}],"project_id":430,"title":"Title"}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer nS9y-ZcClWMZRANFUHGlHwEgIDJ6XYR0j-mq1GlQz10" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/forecasts
POST /1.1/460/forecasts
Accept: application/json
Content-Type: application/json
Authorization: Bearer nS9y-ZcClWMZRANFUHGlHwEgIDJ6XYR0j-mq1GlQz10
Parameters
{"forecast":{"from":"2022-05-10","to":"2022-05-16","estimated_minutes":150,"users":[{"id":996}],"project_id":430,"title":"Title"}}
| Name | Description |
|---|---|
| estimated_minutes | Forecast minutes |
| title | Specifies title for a forecast |
| from | Specifies the “from” time in a timestamp. Example values: from: "2022-05-26T10:00:00+05:30" |
| to | Specifies the “to” time in a timestamp. Example values: to: "2022-05-26T12:00:00+05:30" |
| users | Forecast assignees. Example values: [{ id: 1 }, { id: 3 }] |
| project_id required | The numerical ID of the desired project. Example values: 123 |
| label_ids | Specifies label IDs for a forecast. Example values: label_ids:[2,3,4] |
| external_id | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
Response
Content-Type: application/json; charset=utf-8
201 Created
{
"id": 16,
"note": "Title",
"title": "Title",
"description": "",
"from": "2022-05-10",
"to": "2022-05-16",
"user": {
"id": 996,
"email": "marijajcubqunt@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:18+02:00",
"estimated_minutes": 150,
"estimated_duration": {
"hours": 2,
"minutes": 30,
"seconds": 0,
"formatted": "02:30",
"total_hours": 2.5,
"total_seconds": 9000,
"total_minutes": 150
},
"weekly_capacity": 40.0,
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR"
},
"users": [
{
"id": 996,
"email": "marijajcubqunt@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/dbb51928c4f274ae7070c719550c97c1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:18+02:00",
"estimated_minutes": 0,
"estimated_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"weekly_capacity": 40.0,
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR"
}
],
"project": {
"id": 430,
"active": true,
"name": "Timely",
"color": "67a3bc",
"client": {
"id": 272,
"name": "Dolore quia alias distinctio.",
"color": "00796b",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:18+02:00"
},
"updated_at": "2025-05-13T10:21:18+02:00"
},
"estimated_minutes": 150,
"updated_at": "2025-05-13T10:21:18+02:00",
"created_at": "2025-05-13T10:21:18+02:00",
"label_ids": [],
"estimated_duration": {
"hours": 2,
"minutes": 30,
"seconds": 0,
"formatted": "02:30",
"total_hours": 2.5,
"total_seconds": 9000,
"total_minutes": 150
},
"planned_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"logged_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"completed": false,
"completed_at": null,
"manage": true,
"external_id": null
}
Delete a forecast
Request
curl "https://api.timelyapp.com/1.1/461/forecasts/17" -d '' -X DELETE \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer dWnF7glW1FmBFXy81MNPGN7gPT201tvHVMhZVFwVXqg" \
-H "Cookie: "
Endpoint
DELETE /1.1/:account_id/forecasts/:id
DELETE /1.1/461/forecasts/17
Accept: application/json
Content-Type: application/json
Authorization: Bearer dWnF7glW1FmBFXy81MNPGN7gPT201tvHVMhZVFwVXqg
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the forecast you want to delete |
| id required | The ID for the forecast you want to delete |
Response
Content-Type: application/json; charset=utf-8
200 OK
{}
List all forecasts
Request
curl -g "https://api.timelyapp.com/1.1/462/forecasts" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer hgB9dG_mmRXaZtK1mI12b59iCutEKIEKPpaTViZVbUQ" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/forecasts
GET /1.1/462/forecasts
Accept: application/json
Content-Type: application/json
Authorization: Bearer hgB9dG_mmRXaZtK1mI12b59iCutEKIEKPpaTViZVbUQ
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the forecasts you want to retrieve |
| since | Specifies the start date for returned results. Example: since=2014-08-18 |
| upto | Specifies the end date for returned results. Example: upto=2014-08-24 |
| forecast_ids | Specifies the forecasts for which you want results. Numerical forecast IDs should separated by a comma, like so: "forecast_ids": "175551,117861" |
| user_ids | Specifies the users for which you want results. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861" |
| project_ids | Specifies the projects for which you want results. Numerical project IDs should be separated by a comma, like so: "project_ids": "1751,1171" |
| page | Page number (Default 1) |
| per_page | Records per page (Default 50) |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 18,
"note": "title",
"title": "title",
"description": null,
"from": "2025-05-12",
"to": "2025-05-18",
"user": {
"id": 1003,
"email": "quentincvciikmi@timelyapp.com",
"name": "Quintin Duponde",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/f0612fc2aa39b5f1f2ca545dea8fc84f?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/f0612fc2aa39b5f1f2ca545dea8fc84f?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/f0612fc2aa39b5f1f2ca545dea8fc84f?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/f0612fc2aa39b5f1f2ca545dea8fc84f?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/f0612fc2aa39b5f1f2ca545dea8fc84f?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:19+02:00",
"estimated_minutes": 360,
"estimated_duration": {
"hours": 6,
"minutes": 0,
"seconds": 0,
"formatted": "06:00",
"total_hours": 6.0,
"total_seconds": 21600,
"total_minutes": 360
},
"weekly_capacity": 40.0,
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR"
},
"users": [
{
"id": 1001,
"email": "marijagzksdiag@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/122943a70d5e13953f5916fd8aef3d75?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/122943a70d5e13953f5916fd8aef3d75?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/122943a70d5e13953f5916fd8aef3d75?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/122943a70d5e13953f5916fd8aef3d75?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/122943a70d5e13953f5916fd8aef3d75?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:18+02:00",
"estimated_minutes": 0,
"estimated_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"weekly_capacity": 40.0,
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR"
}
],
"project": {
"id": 432,
"active": true,
"name": "Timely",
"color": "67a3bc",
"client": {
"id": 274,
"name": "Necessitatibus in molestiae dolores.",
"color": "1976d2",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:19+02:00"
},
"updated_at": "2025-05-13T10:21:19+02:00"
},
"estimated_minutes": 360,
"updated_at": "2025-05-13T10:21:19+02:00",
"created_at": "2025-05-13T10:21:19+02:00",
"label_ids": [],
"estimated_duration": {
"hours": 6,
"minutes": 0,
"seconds": 0,
"formatted": "06:00",
"total_hours": 6.0,
"total_seconds": 21600,
"total_minutes": 360
},
"planned_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"logged_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"completed": false,
"completed_at": null,
"manage": true,
"external_id": null
}
]
Update a forecast
Request
curl "https://api.timelyapp.com/1.1/463/forecasts/19" -d '{"forecast":{"from":"2022-05-10","to":"2022-05-16","estimated_minutes":30,"users":[{"id":1004}],"project_id":433,"title":"new title"}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eJTBl241Kr2dUoV41D7iVAgJaln1HuDtGiVTsqviiBA" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/forecasts/:id
PUT /1.1/463/forecasts/19
Accept: application/json
Content-Type: application/json
Authorization: Bearer eJTBl241Kr2dUoV41D7iVAgJaln1HuDtGiVTsqviiBA
Parameters
{"forecast":{"from":"2022-05-10","to":"2022-05-16","estimated_minutes":30,"users":[{"id":1004}],"project_id":433,"title":"new title"}}
| Name | Description |
|---|---|
| id required | Forecast ID |
| estimated_minutes required | Forecast minutes |
| title | Specifies title for a forecast |
| from | Specifies the “from” time in a timestamp. Example values: from: "2022-05-26T10:00:00+05:30" |
| to | Specifies the “to” time in a timestamp. Example values: to: "2022-05-26T12:00:00+05:30" |
| users | Forecast assignees. Example values: [{ id: 1 }, { id: 3 }] |
| project_id required | The numerical ID of the desired project. Example values: 123 |
| label_ids | Specifies label IDs for a forecast. Example values: label_ids:[2,3,4] |
| external_id | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 19,
"note": "new title",
"title": "new title",
"description": "",
"from": "2022-05-10",
"to": "2022-05-16",
"user": {
"id": 1004,
"email": "marijafvrbjrjg@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:19+02:00",
"estimated_minutes": 30,
"estimated_duration": {
"hours": 0,
"minutes": 30,
"seconds": 0,
"formatted": "00:30",
"total_hours": 0.5,
"total_seconds": 1800,
"total_minutes": 30
},
"weekly_capacity": 40.0,
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR"
},
"users": [
{
"id": 1004,
"email": "marijafvrbjrjg@timelyapp.com",
"name": "Marija Petrovic",
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/46c435a005c1b05f011d845cb38934a8?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"updated_at": "2025-05-13T10:21:19+02:00",
"estimated_minutes": 0,
"estimated_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"weekly_capacity": 40.0,
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR"
}
],
"project": {
"id": 433,
"active": true,
"name": "Timely",
"color": "67a3bc",
"client": {
"id": 275,
"name": "Velit eveniet qui modi.",
"color": "2e7d32",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:19+02:00"
},
"updated_at": "2025-05-13T10:21:19+02:00"
},
"estimated_minutes": 30,
"updated_at": "2025-05-13T10:21:19+02:00",
"created_at": "2025-05-13T10:21:19+02:00",
"label_ids": [],
"estimated_duration": {
"hours": 0,
"minutes": 30,
"seconds": 0,
"formatted": "00:30",
"total_hours": 0.5,
"total_seconds": 1800,
"total_minutes": 30
},
"planned_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"logged_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"completed": false,
"completed_at": null,
"manage": true,
"external_id": null
}
Labels
Labels (AKA Tags) help you classify work, group related tasks and require certain information for events. This API lets you to create, list, update and delete tags created on an account.
Create a label
Request
curl "https://api.timelyapp.com/1.1/501/labels" -d '{"name":null,"label":{"name":"Web Programming","active":true}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer B5HuADIG_9DfAw6Bl5UU2HXuoYbzH36iR8UYfMwb4Z4" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/labels
POST /1.1/501/labels
Accept: application/json
Content-Type: application/json
Authorization: Bearer B5HuADIG_9DfAw6Bl5UU2HXuoYbzH36iR8UYfMwb4Z4
Parameters
{"name":null,"label":{"name":"Web Programming","active":true}}
| Name | Description |
|---|---|
| name required | Specifies the label name |
| emoji | Specifies the emoji url for a label |
| parent_id | Set a parent_id if you want to create a child label |
| active | Example values: "true" or "false". Using "false" changes the label state to "archived" |
Response
Content-Type: application/json; charset=utf-8
201 Created
{
"id": 174,
"name": "Web Programming",
"sequence": 1,
"parent_id": null,
"emoji": "https://emoji.memorycdn.com/tw64/1f3f7-fe0f.png",
"active": true,
"created_at": "2025-05-13T10:21:24+02:00",
"updated_at": "2025-05-13T10:21:24+02:00",
"children": []
}
Delete a label
Request
curl "https://api.timelyapp.com/1.1/502/labels/175" -d '' -X DELETE \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer c6W72Y6YCJUzByk0tXabgHlYKXTdIuB8zjh49keGVi0" \
-H "Cookie: "
Endpoint
DELETE /1.1/:account_id/labels/:id
DELETE /1.1/502/labels/175
Accept: application/json
Content-Type: application/json
Authorization: Bearer c6W72Y6YCJUzByk0tXabgHlYKXTdIuB8zjh49keGVi0
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/505/labels?parent_id=177" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YgENg0IofqvdlvFFJIe8k5D2sehO9gACzi1WVdwCQLo" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/labels
GET /1.1/505/labels?parent_id=177
Accept: application/json
Content-Type: application/json
Authorization: Bearer YgENg0IofqvdlvFFJIe8k5D2sehO9gACzi1WVdwCQLo
Parameters
parent_id: 177
| 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": 177,
"name": "Web Programming",
"sequence": 1,
"parent_id": null,
"emoji": null,
"active": true,
"created_at": "2025-05-13T10:21:25+02:00",
"updated_at": "2025-05-13T10:21:25+02:00",
"children": []
}
List all labels
Get all the tags present in user’s account.
Request
curl -g "https://api.timelyapp.com/1.1/504/labels" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer WVQRxOE2v21JVLRXnpg_6m7O99YTKJ1NLrDg9-GVq0w" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/labels
GET /1.1/504/labels
Accept: application/json
Content-Type: application/json
Authorization: Bearer WVQRxOE2v21JVLRXnpg_6m7O99YTKJ1NLrDg9-GVq0w
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the label you want to. retrieve |
| offset | Retrieve labels from offset |
| limit | Retrieve number of labels |
| filter | Specifies which records to retrieve. The default shows a current workspace’s all labels (filter=all). Example: "filter=all" or "filter=active" or "filter=archived" |
Response
Content-Type: application/json; charset=utf-8
200 OK
[]
Retrieve a label
Get single tags present in user’s account.
Request
curl -g "https://api.timelyapp.com/1.1/503/labels/176" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer C7BHokkA4ArsfarITjuDDGiHeVvqI5OuSQH9fGDzsh8" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/labels/:id
GET /1.1/503/labels/176
Accept: application/json
Content-Type: application/json
Authorization: Bearer C7BHokkA4ArsfarITjuDDGiHeVvqI5OuSQH9fGDzsh8
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": 176,
"name": "Web Programming",
"sequence": 1,
"parent_id": null,
"emoji": null,
"active": true,
"created_at": "2025-05-13T10:21:24+02:00",
"updated_at": "2025-05-13T10:21:24+02:00",
"children": []
}
Update a label
Request
curl "https://api.timelyapp.com/1.1/506/labels/178" -d '{"name":null,"label":{"name":"updated name"}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer zbBX8Yww3A4FfQKAywCWMP-LckLn5n2bnM7qTgw--DA" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/labels/:id
PUT /1.1/506/labels/178
Accept: application/json
Content-Type: application/json
Authorization: Bearer zbBX8Yww3A4FfQKAywCWMP-LckLn5n2bnM7qTgw--DA
Parameters
{"name":null,"label":{"name":"updated name"}}
| Name | Description |
|---|---|
| id required | Label ID |
| name required | Specifies the label name |
| emoji | Specifies the emoji url for a tag |
| parent_id | Set a parent_id if you want to create a child label |
| active | Example values: "true" or "false". Using "false" changes the label state to "archived" |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 178,
"name": "updated name",
"sequence": 1,
"parent_id": null,
"emoji": "https://emoji.memorycdn.com/tw64/1f3f7-fe0f.png",
"active": true,
"created_at": "2025-05-13T10:21:25+02:00",
"updated_at": "2025-05-13T10:21:25+02:00",
"children": []
}
Permissions
Retrieve current user's permissions
Using the account id one can see the currently logged user's permissions
Request
curl -g "https://api.timelyapp.com/1.1/517/users/current/permissions" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer byG34Wl7zBnnCA6ZJLucawqkus_cFUnJCQn_z3eK84U" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/users/current/permissions
GET /1.1/517/users/current/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer byG34Wl7zBnnCA6ZJLucawqkus_cFUnJCQn_z3eK84U
Parameters
| Name | Description |
|---|---|
| account_id | Account id for which current user's permissions are to be retrieved |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"resource": "account",
"permissions": [
"create",
"read",
"update",
"manage_plan",
"manage_subscriptions",
"manage_dev"
]
},
{
"resource": "company",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "day_property",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "forecast",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "invoice",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "label",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "project",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "report",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "team",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "user",
"permissions": [
"create",
"delete",
"notify",
"read",
"update"
]
}
]
Retrieve user's permissions by id
Using the account id and user id one can see a specific user's permissions
Request
curl -g "https://api.timelyapp.com/1.1/518/users/1112/permissions" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer nbChdRNHEviCPja1bKWbwvl076flPIYC3-mmQwWbffM" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/users/:user_id/permissions
GET /1.1/518/users/1112/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer nbChdRNHEviCPja1bKWbwvl076flPIYC3-mmQwWbffM
Parameters
| Name | Description |
|---|---|
| account_id | Account for which user's permissions are required |
| user_id | User whose permissions are required |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"resource": "account",
"permissions": [
"create",
"read",
"update",
"manage_plan",
"manage_subscriptions",
"manage_dev"
]
},
{
"resource": "company",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "day_property",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "forecast",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "invoice",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "label",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "project",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "report",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "team",
"permissions": [
"create",
"delete",
"read",
"update"
]
},
{
"resource": "user",
"permissions": [
"create",
"delete",
"notify",
"read",
"update"
]
}
]
Projects
Projects contain all the project details on an account. With this API, you can retrieve, update, create or delete a specific project, or list all projects.
Create a project
Request
curl "https://api.timelyapp.com/1.1/524/projects" -d '{"project":{"name":"New Project","rate_type":"project","hour_rate":50.0,"active":true,"deleted":false,"currency_code":"usd","color":"67a3bc","enable_labels":"all","lock_hours_in":0,"description":"Project Description","client_id":318,"budget_type":"M","budget":300,"users":[{"user_id":1124}],"budget_recurrence":{"recur":"week","start_date":"2018-09-21","end_date":"2019-09-21","recur_until":"end_date"},"labels":[{"label_id":179,"required":true},{"label_id":180,"required":true},{"label_id":181,"required":false},{"label_id":182,"required":false}]},"name":null}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer cXn4Wi9e533TO5jjLfEJdu2B3LX0ftuxUN9UCX34Hdw" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/projects
POST /1.1/524/projects
Accept: application/json
Content-Type: application/json
Authorization: Bearer cXn4Wi9e533TO5jjLfEJdu2B3LX0ftuxUN9UCX34Hdw
Parameters
{"project":{"name":"New Project","rate_type":"project","hour_rate":50.0,"active":true,"deleted":false,"currency_code":"usd","color":"67a3bc","enable_labels":"all","lock_hours_in":0,"description":"Project Description","client_id":318,"budget_type":"M","budget":300,"users":[{"user_id":1124}],"budget_recurrence":{"recur":"week","start_date":"2018-09-21","end_date":"2019-09-21","recur_until":"end_date"},"labels":[{"label_id":179,"required":true},{"label_id":180,"required":true},{"label_id":181,"required":false},{"label_id":182,"required":false}]},"name":null}
| Name | Description |
|---|---|
| project required | Project attributes |
| name required | Specifies the project name |
| color | Specifies the project color. Example values: 1976d2, 00796b, 2e7d32, d4e157, ffeb3b, ffb74d, ff8a65, e57373, b72367, 7e57c2 (when omitted, the client color for the project will be used) |
| client_id required | Specifies the numerical client ID |
| users required | Specifies the project users. It should be an array of users, with numerical user IDs and an hour_rate. For example: "users": [{ "user_id": 175551, "hour_rate": 25.0 },{ "user_id": 117861, "hour_rate": 27.0 }] |
| rate_type required | Specifies the hourly rate type for the project. It should be “user” or “project” |
| 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 |
| external_id | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
| budget_recurrence | Specifies when a recurring budget will refresh |
| send_invite | Specifies if you want to send a project invite email. It should be “true” or “false” |
| required_notes | Project hours notes to be required for logging |
| required_labels | Project hours with atleast one label to be required for logging |
| labels | Specifies the project labels, should be array of labels with numerical label id and required flag Example: "labels": [{ "label_id": 1, "required": true }, { "label_id": 2, "required": false }] |
| enable_labels | Specifies the way labels will be allowed for logging for the project. It should be “all”, “none” or “custom” |
| invoice_by_budget | Specifies if the project's invoices are based on its budget instead of hours. It should be “true“ or “false“ |
| team_ids | Specifies the project teams, should be array of numerical team id's. Example values: team_ids: [3,4,2] |
Response
Content-Type: application/json; charset=utf-8
201 Created
{
"id": 466,
"active": true,
"account_id": 524,
"name": "New Project",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124487,
"updated_at": 1747124487,
"external_id": null,
"budget_scope": null,
"client": {
"id": 318,
"name": "Ea officia est magni.",
"color": "ffb74d",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:27+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": true,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 300,
"budget_type": "M",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"users": [
{
"user_id": 1124,
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"updated_at": "2025-05-13T10:21:27+02:00",
"created_at": "2025-05-13T10:21:27+02:00",
"deleted": false,
"internal_hour_rate": 0,
"internal_hour_rate_in_cents": 0
}
],
"labels": [
{
"project_id": 466,
"label_id": 179,
"budget": 0,
"required": true,
"default": false,
"updated_at": "2025-05-13T10:21:27+02:00"
},
{
"project_id": 466,
"label_id": 180,
"budget": 0,
"required": true,
"default": false,
"updated_at": "2025-05-13T10:21:27+02:00"
},
{
"project_id": 466,
"label_id": 181,
"budget": 0,
"required": false,
"default": false,
"updated_at": "2025-05-13T10:21:27+02:00"
},
{
"project_id": 466,
"label_id": 182,
"budget": 0,
"required": false,
"default": false,
"updated_at": "2025-05-13T10:21:27+02:00"
}
],
"label_ids": [
179,
180,
181,
182
],
"required_label_ids": [
179,
180
],
"default_label_ids": [],
"cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"estimated_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"first_logged_on": null,
"last_logged_on": null,
"budget_recurrence": {
"recur": "week",
"start_date": "2018-09-21",
"end_date": "2019-09-21",
"recur_until": "end_date",
"days_count": 365,
"updated_at": "2025-05-13T10:21:27+02:00"
},
"created_from": "Timely"
}
Delete a project
Request
curl "https://api.timelyapp.com/1.1/525/projects/467" -d '' -X DELETE \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer B81JNzGuZrbAPtGhWPXWknUC0KZ6YcMcELC0vOSQtuA" \
-H "Cookie: "
Endpoint
DELETE /1.1/:account_id/projects/:id
DELETE /1.1/525/projects/467
Accept: application/json
Content-Type: application/json
Authorization: Bearer B81JNzGuZrbAPtGhWPXWknUC0KZ6YcMcELC0vOSQtuA
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the project you want to delete |
| id | The ID of the project you want to delete |
Response
Content-Type: application/json; charset=utf-8
200 OK
{}
List all projects
Note: Admin users can access all projects on an account. Other users can only access the projects they belong to.
Project lists will return your 10000 most recently updated projects. Additionally, you can add the “limit”, “filter (deprecated)”, ”state”, ”relation”, ”sort” and “order” optional parameters to change the result.
Request
curl -g "https://api.timelyapp.com/1.1/527/projects" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer bTvVRxVSZnre3s9gMFClw6JsuXD1hHGLGCtz5FXzVs4" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/projects
GET /1.1/527/projects
Accept: application/json
Content-Type: application/json
Authorization: Bearer bTvVRxVSZnre3s9gMFClw6JsuXD1hHGLGCtz5FXzVs4
Parameters
| Name | Description |
|---|---|
| offset | Retrieve projects from offset |
| limit | Retrieve number of projects |
| sort | Field to sort projects by - updated_at, id, name (Default updated_at) |
| order | Sorting order - desc, asc (Default desc) |
| filter | 🚨 Deprecated: Filter projects - mine, active, archived, all (Default mine, ignored if state or relation parameter is present) |
| state | Filter projects - active, archived, all |
| relation | Filter projects - assigned, created, all |
| updated_after | Retrieve records updated after a certain timestamp |
| project_ids | Retrieve specific projects |
| external_ids | Retrieve specific projects by external ID reference |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 469,
"active": true,
"account_id": 527,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124488,
"updated_at": 1747124488,
"external_id": null,
"budget_scope": null,
"client": {
"id": 321,
"name": "Labore sed suscipit accusantium.",
"color": "d4e157",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:28+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"users": [
{
"user_id": 1130,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000.0,
"updated_at": "2025-05-13T10:21:28+02:00",
"created_at": "2025-05-13T10:21:28+02:00",
"deleted": false,
"internal_hour_rate": 0,
"internal_hour_rate_in_cents": 0
}
],
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"estimated_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"created_from": "Web"
}
]
Retrieve a project Retrieve a single project by using its ID.
Request
curl -g "https://api.timelyapp.com/1.1/526/projects/468" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Cu7jIslHB9sNZm3NO8Vkiz8SapZlHwhk-z5YZqyjIJ8" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/projects/:id
GET /1.1/526/projects/468
Accept: application/json
Content-Type: application/json
Authorization: Bearer Cu7jIslHB9sNZm3NO8Vkiz8SapZlHwhk-z5YZqyjIJ8
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": 468,
"active": true,
"account_id": 526,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124488,
"updated_at": 1747124488,
"external_id": null,
"budget_scope": null,
"client": {
"id": 320,
"name": "Molestias in voluptatibus omnis.",
"color": "d4e157",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:28+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"users": [
{
"user_id": 1128,
"hour_rate": 100.0,
"hour_rate_in_cents": 10000.0,
"updated_at": "2025-05-13T10:21:28+02:00",
"created_at": "2025-05-13T10:21:28+02:00",
"deleted": false,
"internal_hour_rate": 0,
"internal_hour_rate_in_cents": 0
}
],
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"estimated_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"first_logged_on": null,
"last_logged_on": null,
"locked_hours": false,
"created_from": "Web"
}
Update a project
Request
curl "https://api.timelyapp.com/1.1/529/projects/471" -d '{"project":{"name":"updated project name","name":null}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer HR_QpecV2_-J2EtEZTkS6y5xtqhsHRz-p0QKG2de_mM" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/projects/:id
PUT /1.1/529/projects/471
Accept: application/json
Content-Type: application/json
Authorization: Bearer HR_QpecV2_-J2EtEZTkS6y5xtqhsHRz-p0QKG2de_mM
Parameters
{"project":{"name":"updated project name","name":null}}
| Name | Description |
|---|---|
| id required | Project ID |
| project | Project attributes |
| project[name] required | Specifies the project name |
| project[active] | Example values: “true” or “false”. Using “false” changes the project state to “archived” |
| project[color] | Specifies the project color (when omitted, the client color for the project will be used) |
| project[client_id] required | Specifies the numerical client ID |
| project[users] required | Specifies the project users. It should be an array of users, with numerical user IDs and an hour_rate. For example: "users": [{ "user_id": 175551, "hour_rate": 25.0 },{ "user_id": 117861, "hour_rate": 27.0 }] |
| project[billable] | Specifies whether the project is billable or not. It should be “true” or “false” |
| project[budget] | Specifies the budget for the project. It should be numeric value |
| project[hour_rate] | Specifies the hourly rate for the project. It should be numeric value |
| project[rate_type] | Specifies the hourly rate type for the project. It should be “user” or “project” |
| project[external_id] | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
| project[send_invite] | Specifies if you want to send a project invite email. It should be “true” or “false” |
| project[required_notes] | Project hours notes to be required for logging |
| project[required_labels] | Project hours with atleast one label to be required for logging |
| project[enable_labels] | Specifies the way labels will be allowed for logging the project. It should be “all”, “none” or “custom” |
| project[invoice_by_budget] | Specifies if the project's invoices are based on its budget instead of hours. It should be “true“ or “false“. |
| update_existing_hours | Specifies if the rates of existing hours in the project should be updated. It should be "true" or "false". Default: true |
| update_unbilled_only | Specifies if only the rates of unbilled hours in the project should be updated. It is ignored if "update_existing_hours" is false. It should be "true" or "false". Default: false |
| team_ids | Specifies the project teams, should be array of numerical team id's. Example values: team_ids: [3,4,2] |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 471,
"active": true,
"account_id": 529,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124489,
"updated_at": 1747124489,
"external_id": null,
"budget_scope": null,
"client": {
"id": 323,
"name": "Doloremque error eveniet necessitatibus.",
"color": "00796b",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:29+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "none",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "pending",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"users": [
{
"user_id": 1134,
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"updated_at": "2025-05-13T10:21:29+02:00",
"created_at": "2025-05-13T10:21:29+02:00",
"deleted": false,
"internal_hour_rate": 0,
"internal_hour_rate_in_cents": 0
}
],
"labels": [],
"label_ids": [],
"required_label_ids": [],
"default_label_ids": [],
"cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"estimated_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"first_logged_on": null,
"last_logged_on": null,
"created_from": "Web"
}
Reports
Report on activity across your business, including individual and team performance. Export report data from JSON to a format of your choice. Note: .XLS, .CSV and .PDF report formats can only be downloaded from the web UI, not the API.
All Reports For a normal user accessing all account reports.
Note:
1) If start_date and end_date parameters are not passed, the period will default to the beginning-to-end of a month. 2) If user and project parameters are not passed, by default a normal user will get all reports on an account, and a limited user will only get reports they have created. 3) Only normal users can access reports created by other users on an account. Limited users can only access reports they have created. 4) Only normal users can access reports for other projects on an account. Limited users can only access reports for projects they have created.
Request
curl "https://api.timelyapp.com/1.1/571/reports" -d '{"user_ids":"1257","since":"2018-01-01","until":"2019-01-01","project_ids":"574"}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer tzjbTY4aeN9e4_vljcftYmbSIV98AldQgCR5svKdDEQ" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/reports
POST /1.1/571/reports
Accept: application/json
Content-Type: application/json
Authorization: Bearer tzjbTY4aeN9e4_vljcftYmbSIV98AldQgCR5svKdDEQ
Parameters
{"user_ids":"1257","since":"2018-01-01","until":"2019-01-01","project_ids":"574"}
| Name | Description |
|---|---|
| account_id | The account ID containing the report you want to retrieve |
| user_ids | Specifies the users for which you want reports. Numerical user IDs should separated by a comma, like so: "user_ids": "175551,117861" |
| since | Specifies the start date for a report: For example: "since" : "Jan 01, 2014" |
| until | Specifies the end date for a report. For example: "until" : "Dec 31, 2014" |
| project_ids | Specifies the projects for which you want reports. Numerical project IDs should be separated by a comma, like so: "project_ids": "1751,1171" |
| billed | Specifies whether you want to report to show estimated or billed events. For example: "billed": false or "billed": true |
| label_ids | Specifies the labels pertaining to a report you want to see. Numerical label IDs should be separated by a comma, like so: "label_ids": [751,117] or "751,117". Result will include any of provided values. |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 365,
"name": "Tenetur omnis dolor quisquam.",
"projects": [
{
"id": 574,
"active": true,
"account_id": 571,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124502,
"updated_at": 1747124502,
"external_id": null,
"budget_scope": null,
"client": {
"id": 365,
"name": "Tenetur omnis dolor quisquam.",
"color": "00796b",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:42+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"estimated_duration": {
"hours": 8,
"minutes": 0,
"seconds": 0,
"formatted": "08:00",
"total_hours": 8.0,
"total_seconds": 28800,
"total_minutes": 480
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"billable_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 80000,
"formatted": "$800.00",
"amount": 800.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 75000,
"formatted": "$750.00",
"amount": 750.0,
"currency_code": "usd"
},
"profit": {
"fractional": -25000,
"formatted": "$-250.00",
"amount": -250.0,
"currency_code": "usd"
},
"profitability": 0,
"created_from": "Web"
}
],
"duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"estimated_duration": {
"hours": 8,
"minutes": 0,
"seconds": 0,
"formatted": "08:00",
"total_hours": 8.0,
"total_seconds": 28800,
"total_minutes": 480
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"billable_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 80000,
"formatted": "$800.00",
"amount": 800.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 75000,
"formatted": "$750.00",
"amount": 750.0,
"currency_code": "usd"
},
"profit": {
"fractional": -25000,
"formatted": "$-250.00",
"amount": -250.0,
"currency_code": "usd"
},
"profitability": 0
}
]
Filter reports
Use filter endpoints with parameters to limit returned data, so you only see the values that you need.
Request
curl "https://api.timelyapp.com/1.1/572/reports/filter" -d '{"user_ids":"1259","since":"2018-01-01","until":"2019-01-01","project_ids":"575"}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer POjeXase52v2M8r8BtLjndPbCp0sGQh7wpklaBp_rKw" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/reports/filter
POST /1.1/572/reports/filter
Accept: application/json
Content-Type: application/json
Authorization: Bearer POjeXase52v2M8r8BtLjndPbCp0sGQh7wpklaBp_rKw
Parameters
{"user_ids":"1259","since":"2018-01-01","until":"2019-01-01","project_ids":"575"}
| Name | Description |
|---|---|
| billed | Retrieve billed hours only. Example: billed=true |
| label_ids | Specifies the label IDs of the hours you want to retrieve. Label IDs should be a numerical array, like so: label_ids: [3,4,2] or "3,4,2". Result will include any of provided values. |
| project_ids | Specifies the project IDs of the hours you want to retrieve. Project IDs should be a numerical array, like so: project_ids: [3,4,2] |
| since | The start date of a report. For example: 'since=2019-01-01' |
| team_ids | Specifies the team IDs of the hours you want to retrieve. Team IDs should be a numerical array, like so: team_ids: [3,4,2] |
| until | The end date of a report. For example: 'until=2019-12-31'' |
| user_ids | Specifies the user IDs of the hours you want to retrieve. User IDs should be a numerical array, like so: user_ids: [3,4,2] |
| group_by | Specifies how to group the hours. Default: group_by: ["clients", "users", "labels", "days", "teams"] |
| scope | Retrieve events only. For example: 'scope=events' |
| offset | Retrieve records from offset (Default 0). |
| limit | Retrieve number of records. Max 100 records. |
| page | Page number (Default 1). |
| locked | Retrieve locked hours only. Example: locked=true |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"multiple_currency_report": false,
"totals": {
"duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"estimated_duration": {
"hours": 8,
"minutes": 0,
"seconds": 0,
"formatted": "08:00",
"total_hours": 8.0,
"total_seconds": 28800,
"total_minutes": 480
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"billable_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 80000,
"formatted": "$800.00",
"amount": 800.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 75000,
"formatted": "$750.00",
"amount": 750.0,
"currency_code": "usd"
},
"profit": {
"fractional": -25000,
"formatted": "$-250.00",
"amount": -250.0,
"currency_code": "usd"
},
"profitability": 0
},
"clients": [
{
"id": 366,
"name": "Veritatis nihil reiciendis provident.",
"projects": [
{
"id": 575,
"active": true,
"account_id": 572,
"name": "Timely",
"description": "Project Description",
"color": "67a3bc",
"rate_type": "project",
"billable": true,
"created_at": 1747124503,
"updated_at": 1747124503,
"external_id": null,
"budget_scope": null,
"client": {
"id": 366,
"name": "Veritatis nihil reiciendis provident.",
"color": "1976d2",
"active": true,
"external_id": null,
"updated_at": "2025-05-13T10:21:43+02:00"
},
"required_notes": false,
"required_labels": false,
"budget_expired_on": null,
"has_recurrence": false,
"enable_labels": "all",
"default_labels": false,
"currency": {
"id": "usd",
"name": "United States Dollar",
"iso_code": "USD",
"symbol": "$",
"symbol_first": true
},
"team_ids": [],
"budget": 0,
"budget_type": "",
"budget_calculation": "completed",
"hour_rate": 50.0,
"hour_rate_in_cents": 5000.0,
"budget_progress": 0.0,
"budget_percent": 0.0,
"invoice_by_budget": false,
"duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"estimated_duration": {
"hours": 8,
"minutes": 0,
"seconds": 0,
"formatted": "08:00",
"total_hours": 8.0,
"total_seconds": 28800,
"total_minutes": 480
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"billable_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 80000,
"formatted": "$800.00",
"amount": 800.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 75000,
"formatted": "$750.00",
"amount": 750.0,
"currency_code": "usd"
},
"profit": {
"fractional": -25000,
"formatted": "$-250.00",
"amount": -250.0,
"currency_code": "usd"
},
"profitability": 0,
"created_from": "Web"
}
],
"duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"estimated_duration": {
"hours": 8,
"minutes": 0,
"seconds": 0,
"formatted": "08:00",
"total_hours": 8.0,
"total_seconds": 28800,
"total_minutes": 480
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"billable_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 80000,
"formatted": "$800.00",
"amount": 800.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 75000,
"formatted": "$750.00",
"amount": 750.0,
"currency_code": "usd"
},
"profit": {
"fractional": -25000,
"formatted": "$-250.00",
"amount": -250.0,
"currency_code": "usd"
},
"profitability": 0
}
],
"users": [
{
"id": 1259,
"email": "marijadpfqlhfg@timelyapp.com",
"name": "Marija Petrovic",
"time_zone": "Europe/Paris",
"updated_at": 1747124503,
"active": false,
"deleted": false,
"memory_onboarded": true,
"day_view_onboarded": true,
"last_received_memories_date": null,
"date_format": "dmy",
"time_format": "24",
"memory_retention_days": null,
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/18d6e7a58565cf904f20041accc93f5a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/18d6e7a58565cf904f20041accc93f5a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=",
"medium_retina": "https://www.gravatar.com/avatar/18d6e7a58565cf904f20041accc93f5a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/18d6e7a58565cf904f20041accc93f5a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=",
"timeline": "https://www.gravatar.com/avatar/18d6e7a58565cf904f20041accc93f5a?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_timeline-e61ac46443487bd24fbaecab08cfacf5d0835b371cbe97a33b9e738744ef8334.jpg&s="
},
"duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"estimated_duration": {
"hours": 8,
"minutes": 0,
"seconds": 0,
"formatted": "08:00",
"total_hours": 8.0,
"total_seconds": 28800,
"total_minutes": 480
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"billable_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 80000,
"formatted": "$800.00",
"amount": 800.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 75000,
"formatted": "$750.00",
"amount": 750.0,
"currency_code": "usd"
},
"profit": {
"fractional": -25000,
"formatted": "$-250.00",
"amount": -250.0,
"currency_code": "usd"
},
"profitability": 0,
"capacity": {
"hours": 2096,
"minutes": 0,
"seconds": 0.0,
"formatted": "2096:00",
"total_hours": 2096.0,
"total_seconds": 7545600.0,
"total_minutes": 125760.0
},
"overtime": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"undertime": {
"hours": 2091,
"minutes": 0,
"seconds": 0.0,
"formatted": "2091:00",
"total_hours": 2091.0,
"total_seconds": 7527600.0,
"total_minutes": 125460.0
}
}
],
"labels": [
{
"id": 0,
"name": "Untagged",
"sequence": -1,
"parent_id": null,
"emoji": "https://emoji.memorycdn.com/tw64/1f3f7.png",
"active": true,
"created_at": null,
"updated_at": null,
"children": [],
"duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"estimated_duration": {
"hours": 8,
"minutes": 0,
"seconds": 0,
"formatted": "08:00",
"total_hours": 8.0,
"total_seconds": 28800,
"total_minutes": 480
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"billable_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 80000,
"formatted": "$800.00",
"amount": 800.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 75000,
"formatted": "$750.00",
"amount": 750.0,
"currency_code": "usd"
},
"profit": {
"fractional": -25000,
"formatted": "$-250.00",
"amount": -250.0,
"currency_code": "usd"
},
"profitability": 0
}
],
"days": [
{
"day": "2018-01-02",
"duration": {
"hours": 2,
"minutes": 30,
"seconds": 0,
"formatted": "02:30",
"total_hours": 2.5,
"total_seconds": 9000,
"total_minutes": 150
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 2,
"minutes": 30,
"seconds": 0,
"formatted": "02:30",
"total_hours": 2.5,
"total_seconds": 9000,
"total_minutes": 150
},
"billable_duration": {
"hours": 2,
"minutes": 30,
"seconds": 0,
"formatted": "02:30",
"total_hours": 2.5,
"total_seconds": 9000,
"total_minutes": 150
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 25000,
"formatted": "$250.00",
"amount": 250.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 25000,
"formatted": "$250.00",
"amount": 250.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 37500,
"formatted": "$375.00",
"amount": 375.0,
"currency_code": "usd"
},
"profit": {
"fractional": -12500,
"formatted": "$-125.00",
"amount": -125.0,
"currency_code": "usd"
},
"profitability": 0
},
{
"day": "2018-01-01",
"duration": {
"hours": 2,
"minutes": 30,
"seconds": 0,
"formatted": "02:30",
"total_hours": 2.5,
"total_seconds": 9000,
"total_minutes": 150
},
"estimated_duration": {
"hours": 4,
"minutes": 0,
"seconds": 0,
"formatted": "04:00",
"total_hours": 4.0,
"total_seconds": 14400,
"total_minutes": 240
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 2,
"minutes": 30,
"seconds": 0,
"formatted": "02:30",
"total_hours": 2.5,
"total_seconds": 9000,
"total_minutes": 150
},
"billable_duration": {
"hours": 2,
"minutes": 30,
"seconds": 0,
"formatted": "02:30",
"total_hours": 2.5,
"total_seconds": 9000,
"total_minutes": 150
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 25000,
"formatted": "$250.00",
"amount": 250.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 40000,
"formatted": "$400.00",
"amount": 400.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 25000,
"formatted": "$250.00",
"amount": 250.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 37500,
"formatted": "$375.00",
"amount": 375.0,
"currency_code": "usd"
},
"profit": {
"fractional": -12500,
"formatted": "$-125.00",
"amount": -125.0,
"currency_code": "usd"
},
"profitability": 0
}
],
"teams": [
{
"id": 0,
"name": "No team",
"color": "866b9c",
"emoji": "https://emoji.memorycdn.com/tw64/1f465.png",
"external_id": null,
"duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"estimated_duration": {
"hours": 8,
"minutes": 0,
"seconds": 0,
"formatted": "08:00",
"total_hours": 8.0,
"total_seconds": 28800,
"total_minutes": 480
},
"billed_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"unbilled_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"billable_duration": {
"hours": 5,
"minutes": 0,
"seconds": 0,
"formatted": "05:00",
"total_hours": 5.0,
"total_seconds": 18000,
"total_minutes": 300
},
"non_billable_duration": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"estimated_cost": {
"fractional": 80000,
"formatted": "$800.00",
"amount": 800.0,
"currency_code": "usd"
},
"billed_cost": {
"fractional": 0,
"formatted": "$0.00",
"amount": 0.0,
"currency_code": "usd"
},
"unbilled_cost": {
"fractional": 50000,
"formatted": "$500.00",
"amount": 500.0,
"currency_code": "usd"
},
"internal_cost": {
"fractional": 75000,
"formatted": "$750.00",
"amount": 750.0,
"currency_code": "usd"
},
"profit": {
"fractional": -25000,
"formatted": "$-250.00",
"amount": -250.0,
"currency_code": "usd"
},
"profitability": 0,
"capacity": {
"hours": 2096,
"minutes": 0,
"seconds": 0.0,
"formatted": "2096:00",
"total_hours": 2096.0,
"total_seconds": 7545600.0,
"total_minutes": 125760.0
},
"overtime": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"formatted": "00:00",
"total_hours": 0.0,
"total_seconds": 0,
"total_minutes": 0
},
"undertime": {
"hours": 2091,
"minutes": 0,
"seconds": 0.0,
"formatted": "2091:00",
"total_hours": 2091.0,
"total_seconds": 7527600.0,
"total_minutes": 125460.0
}
}
]
}
Roles
List roles
Note: default attribute shows which role to select by default
Request
curl -g "https://api.timelyapp.com/1.1/573/roles" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer qVbgvub4DlOYcW7je2AKlMh6qMZnpw_RTpn3EbbeT5U" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/roles
GET /1.1/573/roles
Accept: application/json
Content-Type: application/json
Authorization: Bearer qVbgvub4DlOYcW7je2AKlMh6qMZnpw_RTpn3EbbeT5U
Parameters
| Name | Description |
|---|---|
| account_id | Account id for which roles are required |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 2291,
"name": "admin",
"display_name": "Admin",
"description": "Can see, create and edit all hours, projects and teams.",
"scopes": [
{
"name": "hide_hourly_rate",
"display_name": "Hide billable rate",
"description": "Hide hourly rates for this user",
"default": false,
"options": [
false
]
},
{
"name": "hide_internal_hourly_rate",
"display_name": "Hide cost rate",
"description": "Hide internal hourly rates for this user",
"default": false,
"options": [
false
]
}
],
"default": false,
"allowed_to_invite": true
},
{
"id": 2293,
"name": "employee",
"display_name": "Employee",
"description": "Can only see, log and edit their own hours.",
"scopes": [
{
"name": "hide_hourly_rate",
"display_name": "Hide billable rate",
"description": "Hide hourly rates for this user",
"default": false,
"options": [
true,
false
]
},
{
"name": "hide_internal_hourly_rate",
"display_name": "Hide cost rate",
"description": "Hide internal hourly rates for this user",
"default": true,
"options": [
true,
false
]
}
],
"default": false,
"allowed_to_invite": true
},
{
"id": 2292,
"name": "manager",
"display_name": "Manager",
"description": "Can see, log and edit hours for anyone on the same project as them.",
"scopes": [
{
"name": "hide_hourly_rate",
"display_name": "Hide billable rate",
"description": "Hide hourly rates for this user",
"default": false,
"options": [
true,
false
]
},
{
"name": "hide_internal_hourly_rate",
"display_name": "Hide cost rate",
"description": "Hide internal hourly rates for this user",
"default": true,
"options": [
true,
false
]
}
],
"default": true,
"allowed_to_invite": true
},
{
"id": 2294,
"name": "team_lead",
"display_name": "Team Lead",
"description": "Can see, log and edit hours for anyone from the team they lead",
"scopes": [
{
"name": "hide_hourly_rate",
"display_name": "Hide billable rate",
"description": "Hide hourly rates for this user",
"default": false,
"options": [
true,
false
]
},
{
"name": "hide_internal_hourly_rate",
"display_name": "Hide cost rate",
"description": "Hide internal hourly rates for this user",
"default": true,
"options": [
true,
false
]
}
],
"default": false,
"allowed_to_invite": false
}
]
Teams
The team object shows all teams available on an account.
Create a team
Request
curl "https://api.timelyapp.com/1.1/596/teams" -d '{"name":null,"team":{"name":"Timely","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":1307,"lead":true},{"user_id":1309,"lead":false}]}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer P2J98pJv80QrBav2jgoTTBvg4r8kln4UJkh6JLuupVE" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/teams
POST /1.1/596/teams
Accept: application/json
Content-Type: application/json
Authorization: Bearer P2J98pJv80QrBav2jgoTTBvg4r8kln4UJkh6JLuupVE
Parameters
{"name":null,"team":{"name":"Timely","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":1307,"lead":true},{"user_id":1309,"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": 44,
"name": "Timely",
"color": "67a3bc",
"emoji": "http://path.to/emoji.png",
"external_id": null,
"project_ids": [],
"user_ids": [
1307,
1309
],
"users": [
{
"id": 80,
"user_id": 1307,
"team_id": 44,
"lead": true,
"hide_hours": false
},
{
"id": 81,
"user_id": 1309,
"team_id": 44,
"lead": false,
"hide_hours": false
}
]
}
Delete a team
Request
curl "https://api.timelyapp.com/1.1/597/teams/45" -d '' -X DELETE \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 9Ni-HeTp2oEu4gUY-qDJE-pH6ppCKBlqwtGESsfVrRI" \
-H "Cookie: "
Endpoint
DELETE /1.1/:account_id/teams/:id
DELETE /1.1/597/teams/45
Accept: application/json
Content-Type: application/json
Authorization: Bearer 9Ni-HeTp2oEu4gUY-qDJE-pH6ppCKBlqwtGESsfVrRI
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the team you want to delete |
| id | The ID of the team you want to delete |
| delete_project_users | Specifies if associated users should be removed from team projects. For example: "delete_project_users":true. Default: false |
Response
Content-Type: application/json; charset=utf-8
200 OK
{}
List all teams
Request
curl -g "https://api.timelyapp.com/1.1/599/teams" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer V3UJ9g1p6TltTfuvnVgQKwEbqoGyEsU9V42oE5rp3kA" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/teams
GET /1.1/599/teams
Accept: application/json
Content-Type: application/json
Authorization: Bearer V3UJ9g1p6TltTfuvnVgQKwEbqoGyEsU9V42oE5rp3kA
Parameters
| Name | Description |
|---|---|
| page | Page number (Default 1) |
| per_page | Records per page (Default 50) |
| order | Sorting order on name |
| filter | Filter teams - mine, all |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 47,
"name": "Timely",
"color": "67a3bc",
"emoji": "http://path.to/emoji.png",
"external_id": null,
"project_ids": [],
"user_ids": [],
"users": []
}
]
Retrieve a team
Request
curl -g "https://api.timelyapp.com/1.1/598/teams/46" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer -fiCnDE8a-2xBZ0eR7cCeRi3SRmukCVcP5GxdpiYD08" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/teams/:id
GET /1.1/598/teams/46
Accept: application/json
Content-Type: application/json
Authorization: Bearer -fiCnDE8a-2xBZ0eR7cCeRi3SRmukCVcP5GxdpiYD08
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the team you want to retrieve |
| id | The ID of the team you want to retrieve |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 46,
"name": "Timely",
"color": "67a3bc",
"emoji": "http://path.to/emoji.png",
"external_id": null,
"project_ids": [],
"user_ids": [],
"users": []
}
Update a team
Request
curl "https://api.timelyapp.com/1.1/600/teams/48" -d '{"name":null,"team":{"name":"Backend","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":1316,"lead":true}]}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Hd5JoKroaqjN1uuXSSz9DT_IABG8F1tr4OQh4PKopNg" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/teams/:id
PUT /1.1/600/teams/48
Accept: application/json
Content-Type: application/json
Authorization: Bearer Hd5JoKroaqjN1uuXSSz9DT_IABG8F1tr4OQh4PKopNg
Parameters
{"name":null,"team":{"name":"Backend","color":"67a3bc","emoji":"http://path.to/emoji.png","external_id":null,"users":[{"user_id":1316,"lead":true}]}}
| Name | Description |
|---|---|
| name required | Specifies the team name |
| emoji | Specifies the emoji url for a team |
| color | Specifies the project color for a team |
| external_id | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
| users required | Specific users with their role in the team. Ex: users:[{'user_id': 1, 'lead': true}] |
| add_users_to_team_projects | Specifies if the user should be added to team projects. For example: "add_users_to_team_projects":false. Default: true |
| delete_users_from_team_projects | Specifies if the removed user should be removed from team projects. For example: "delete_users_from_team_projects":true. Default: false |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 48,
"name": "Backend",
"color": "67a3bc",
"emoji": "http://path.to/emoji.png",
"external_id": null,
"project_ids": [],
"user_ids": [
1316
],
"users": [
{
"id": 82,
"user_id": 1316,
"team_id": 48,
"lead": true,
"hide_hours": false
}
]
}
UserCapacities
Retrieve capacities
See capacities of multiple users in the account
Request
curl -g "https://api.timelyapp.com/1.1/605/users/capacities" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer FRyEv-VirrmtXNUeFsmwz253lktRzvcv3WQTuGhvLSk" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/users/capacities
GET /1.1/605/users/capacities
Accept: application/json
Content-Type: application/json
Authorization: Bearer FRyEv-VirrmtXNUeFsmwz253lktRzvcv3WQTuGhvLSk
Parameters
| Name | Description |
|---|---|
| account_id required | Account for which users' capacities are required |
| user_ids | Users whose capacities are required |
| since | Fetch capacities after selected date |
| until | Fetch capacities before selected date |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"user_id": 1326,
"capacities": [
{
"id": null,
"weekly_capacity": 40.0,
"daily_capacity": 8.0,
"weekdays": "MO,TU,WE,TH,FR",
"work_days": "MON,TUE,WED,THU,FRI",
"total_working_days": null,
"weekly_working_days": 5,
"current": true,
"start_date": "1970-01-01",
"end_date": null
}
]
}
]
Retrieve user's capacities
Using the user id one can see the user's capacities
Request
curl -g "https://api.timelyapp.com/1.1/604/users/1324/capacities" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer oHlWSEWjELyGR_ZlVq4eM3v1FrHMHWVawIId4o6ZClM" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/users/:user_id/capacities
GET /1.1/604/users/1324/capacities
Accept: application/json
Content-Type: application/json
Authorization: Bearer oHlWSEWjELyGR_ZlVq4eM3v1FrHMHWVawIId4o6ZClM
Parameters
| Name | Description |
|---|---|
| account_id required | Account for which user's capacities are required |
| user_id required | User whose capacities are required |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": null,
"weekly_capacity": 40.0,
"daily_capacity": 8.0,
"weekdays": "MO,TU,WE,TH,FR",
"work_days": "MON,TUE,WED,THU,FRI",
"total_working_days": null,
"weekly_working_days": 5,
"current": true,
"start_date": "1970-01-01",
"end_date": null
}
]
Users
An account can have multiple users associated with it. All users have a specific access level, and are usually created by an employer on behalf of an employee.
Create/Invite a user
Note: user_level can have values “normal” or “limited”. A user’s name and email can only be updated by the user themself.
Request
curl "https://api.timelyapp.com/1.1/607/users" -d '{"user":{"name":"Marija Petrovic","email":"marija@timely.com","user_level":"normal","admin":false,"projects":[{"project_id":609,"hour_rate":10}]},"name":null,"admin":{"id":302,"email":"notifications@timelyapp.com","created_at":"2025-05-13T08:21:52.000Z","updated_at":"2025-05-13T08:21:52.000Z","name":"Timely","notifier":true}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer V2zEFwOcThXlTbSBsQ_N4rZBtcMzXhWyvYKrcBn29fc" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/users
POST /1.1/607/users
Accept: application/json
Content-Type: application/json
Authorization: Bearer V2zEFwOcThXlTbSBsQ_N4rZBtcMzXhWyvYKrcBn29fc
Parameters
{"user":{"name":"Marija Petrovic","email":"marija@timely.com","user_level":"normal","admin":false,"projects":[{"project_id":609,"hour_rate":10}]},"name":null,"admin":{"id":302,"email":"notifications@timelyapp.com","created_at":"2025-05-13T08:21:52.000Z","updated_at":"2025-05-13T08:21:52.000Z","name":"Timely","notifier":true}}
| Name | Description |
|---|---|
| user required | User attributes |
| name required | Specifies the user name |
| email required | Specifies the user email |
| projects | Description: Specifies the projects that the user will be part of. For example: "projects": [ {"project_id": 11 , "hour_rate": 10 }, {"project_id": 12 , "hour_rate": 20 }] |
| role_id required | Specifies the user's role in the account |
| user_level | (Deprecated) Specifies the user level; either “normal” or “limited”. The default is "normal". For example: "user_level": "normal" |
| admin | (Deprecated) Specifies the user is an admin. In this case user_level should be “normal”. For example: "admin": "true" |
| external_id | The external_id can be used to reference external resource IDs to Timely resources, and should be alphanumeric (max. 512 characters) |
| weekly_capacity | Specifies the user's weekly hour capacity. The default is account's weekly capacity. To avoid rounding issues, values are allowed upto 1 decimal place and divisible by 5. |
| add_to_all_projects | Specifies whether the user should be added to all projects in the account. For example: "add_to_all_projects":true |
| internal_hour_rate | Specifies the internal hourly rate for users in the account |
| hide_internal_hourly_rate | The hide_internal_hourly_rate hides the internal hourly rate for users in the account. The default is true. For example: "hide_internal_hourly_rate": true |
| team_ids | Specifies the teams that the user will be part of, should be array of numerical team id's. Example values: team_ids: [3,4,2] |
| add_team_users_to_projects | Specifies if the user should be added to team projects Specified in team_ids. For example: "add_team_users_to_projects":false. Default: true |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 1332,
"email": "marija@timely.com",
"name": "Marija Petrovic",
"active": false,
"day_view_onboarded": false,
"memory_onboarded": false,
"created_at": 1747124512,
"updated_at": 1747124512,
"last_received_memories_date": null,
"sign_in_count": null,
"external_id": null,
"time_zone": "Etc/UTC",
"memory_retention_days": null,
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"medium_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"small_retina": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
"small": "https://www.gravatar.com/avatar/0a8763ca707efea0026580f1712c3fe0?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
},
"type": "User",
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR",
"weekly_capacity": 40.0,
"user_level": "manager",
"admin": false,
"hide_hourly_rate": false,
"hide_internal_hourly_rate": false,
"deleted": false,
"default_hour_rate": 0.0,
"internal_hour_rate": 0.0,
"role_id": 2428,
"role": {
"id": 2428,
"name": "manager"
}
}
Delete a user
Request
curl "https://api.timelyapp.com/1.1/608/users/1333" -d '' -X DELETE \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer _H9Y5tOFLIE00RMF8_Ixoeu-sGUjO5mQoPjaHSakI7c" \
-H "Cookie: "
Endpoint
DELETE /1.1/:account_id/users/:id
DELETE /1.1/608/users/1333
Accept: application/json
Content-Type: application/json
Authorization: Bearer _H9Y5tOFLIE00RMF8_Ixoeu-sGUjO5mQoPjaHSakI7c
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the user you want to delete |
| id | The ID of the user you want to delete |
Response
Content-Type: application/json; charset=utf-8
200 OK
{}
List all users
Note: The user list will return the 100 most recently updated users.
Request
curl -g "https://api.timelyapp.com/1.1/611/users" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Es5d0dQXcHu7ls_slC5CuY3EwgolxXFw0229edj29DU" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/users
GET /1.1/611/users
Accept: application/json
Content-Type: application/json
Authorization: Bearer Es5d0dQXcHu7ls_slC5CuY3EwgolxXFw0229edj29DU
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the users you want to retrieve |
| limit | Retrieve a limited number of users (Default 100) |
| offset | Retrieve users from offset |
| order | Sorting order on updated_at - desc, asc (Default desc) |
| filter | Filter users - active, deleted (Default active) |
Response
Content-Type: application/json; charset=utf-8
200 OK
[
{
"id": 1339,
"email": "marijaprfiemxz@timelyapp.com",
"name": "Marija Petrovic",
"active": false,
"day_view_onboarded": true,
"memory_onboarded": true,
"created_at": 1747124513,
"updated_at": 1747124513,
"last_received_memories_date": null,
"sign_in_count": null,
"external_id": null,
"time_zone": "Europe/Paris",
"memory_retention_days": null,
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/c21c059f58d06738e924c87110c57699?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/c21c059f58d06738e924c87110c57699?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"medium_retina": "https://www.gravatar.com/avatar/c21c059f58d06738e924c87110c57699?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/c21c059f58d06738e924c87110c57699?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"small_retina": "https://www.gravatar.com/avatar/c21c059f58d06738e924c87110c57699?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
"small": "https://www.gravatar.com/avatar/c21c059f58d06738e924c87110c57699?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
},
"type": "User",
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR",
"weekly_capacity": 40.0,
"user_level": "admin",
"admin": true,
"hide_hourly_rate": false,
"hide_internal_hourly_rate": true,
"deleted": false,
"default_hour_rate": 0.0,
"internal_hour_rate": 0.0,
"role_id": 2443,
"role": {
"id": 2443,
"name": "admin"
}
}
]
Retrieve a user
Request
curl -g "https://api.timelyapp.com/1.1/609/users/1335" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3FrZySJ24_MgDNdpTp3_dHu8Y0Uz1QrJYhn0oDWf-dk" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/users/:id
GET /1.1/609/users/1335
Accept: application/json
Content-Type: application/json
Authorization: Bearer 3FrZySJ24_MgDNdpTp3_dHu8Y0Uz1QrJYhn0oDWf-dk
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": 1335,
"email": "marijafzhywqmm@timelyapp.com",
"name": "Marija Petrovic",
"active": false,
"day_view_onboarded": true,
"memory_onboarded": true,
"created_at": 1747124512,
"updated_at": 1747124512,
"last_received_memories_date": null,
"sign_in_count": null,
"external_id": null,
"time_zone": "Europe/Paris",
"memory_retention_days": null,
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/8de6ef8f15cbb68f70ca7d14fffdce60?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/8de6ef8f15cbb68f70ca7d14fffdce60?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"medium_retina": "https://www.gravatar.com/avatar/8de6ef8f15cbb68f70ca7d14fffdce60?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/8de6ef8f15cbb68f70ca7d14fffdce60?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"small_retina": "https://www.gravatar.com/avatar/8de6ef8f15cbb68f70ca7d14fffdce60?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
"small": "https://www.gravatar.com/avatar/8de6ef8f15cbb68f70ca7d14fffdce60?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
},
"type": "User",
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR",
"weekly_capacity": 40.0,
"active_projects_count": 1,
"user_level": "admin",
"admin": true,
"hide_hourly_rate": false,
"hide_internal_hourly_rate": true,
"deleted": false,
"default_hour_rate": 0.0,
"internal_hour_rate": 0.0,
"role_id": 2435,
"role": {
"id": 2435,
"name": "admin"
}
}
Retrieve current user
Request
curl -g "https://api.timelyapp.com/1.1/610/users/current" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer -39KyHbEqKBA6iIN99DkQsTAdM0WSndWGGUtFaUuxBc" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/users/current
GET /1.1/610/users/current
Accept: application/json
Content-Type: application/json
Authorization: Bearer -39KyHbEqKBA6iIN99DkQsTAdM0WSndWGGUtFaUuxBc
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the current user |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 1337,
"email": "marijaqroqldmk@timelyapp.com",
"name": "Marija Petrovic",
"active": false,
"day_view_onboarded": true,
"memory_onboarded": true,
"created_at": 1747124513,
"updated_at": 1747124513,
"last_received_memories_date": null,
"sign_in_count": null,
"external_id": null,
"time_zone": "Europe/Paris",
"memory_retention_days": null,
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/8f74f588c97036d51b492f81f49efcb1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/8f74f588c97036d51b492f81f49efcb1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"medium_retina": "https://www.gravatar.com/avatar/8f74f588c97036d51b492f81f49efcb1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/8f74f588c97036d51b492f81f49efcb1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"small_retina": "https://www.gravatar.com/avatar/8f74f588c97036d51b492f81f49efcb1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
"small": "https://www.gravatar.com/avatar/8f74f588c97036d51b492f81f49efcb1?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
},
"type": "User",
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR",
"weekly_capacity": 40.0,
"user_level": "admin",
"admin": true,
"hide_hourly_rate": false,
"hide_internal_hourly_rate": true,
"deleted": false,
"default_hour_rate": 0.0,
"internal_hour_rate": 0.0,
"role_id": 2439,
"role": {
"id": 2439,
"name": "admin"
}
}
Update a user
Note:
Please use the parameters mentioned in “Create/Invite a user”.
Only admins can edit “user_level” and “projects” fields for other users.
Request
curl "https://api.timelyapp.com/1.1/612/users/1341" -d '{"user":{"admin":{"id":307,"email":"notifications@timelyapp.com","created_at":"2025-05-13T08:21:54.000Z","updated_at":"2025-05-13T08:21:54.000Z","name":"Timely","notifier":true},"role_id":2447,"projects":[{"project_id":614,"hour_rate":10}]}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer zV2JJXRT7KI4PAWs-NmYN4otJIdDvkR3Zj7FRAuuJsQ" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/users/:id
PUT /1.1/612/users/1341
Accept: application/json
Content-Type: application/json
Authorization: Bearer zV2JJXRT7KI4PAWs-NmYN4otJIdDvkR3Zj7FRAuuJsQ
Parameters
{"user":{"admin":{"id":307,"email":"notifications@timelyapp.com","created_at":"2025-05-13T08:21:54.000Z","updated_at":"2025-05-13T08:21:54.000Z","name":"Timely","notifier":true},"role_id":2447,"projects":[{"project_id":614,"hour_rate":10}]}}
| Name | Description |
|---|---|
| id required | The numerical ID of the user |
| user required | Label attributes |
| user[projects] | Specifies the projects that the user will be part of. For example: "projects": [ {"project_id": 11 , "hour_rate": 10 }, {"project_id": 12 , "hour_rate": 20 }] |
| user[role_id] required | Specifies the user's role in the account |
| user[user_level] | (Deprecated) Specifies the user level; either “normal” or “limited”. The default is "normal". For example: "user_level": "normal" |
| user[admin] | (Deprecated) Specifies the user is an admin. In this case user_level should be “normal”. For example: "admin": "true" |
| user[weekly_capacity] | Specifies the user's weekly hour capacity. The default is the account's weekly capacity. To avoid rounding issues, values are allowed upto 1 decimal place and divisible by 5. |
| user[add_to_all_projects] | Specifies whether the user should be added to all projects in the account. For example: "add_to_all_projects":true |
| user[internal_hour_rate] | Specifies the internal hourly rate for users in the account |
| user[hide_internal_hourly_rate] | The hide_internal_hourly_rate hides the internal hourly rate for users in the account. The default is true. For example: "hide_internal_hourly_rate": true |
| update_existing_hours | Specifies if the updated hour rate should be applied to existing hours. For example: "update_existing_hours":false. Default: true |
| update_unbilled_only | Specifies if the updated hour rate should only be applied to unbilled hours. This is ignored if "update_existing_hours" is false. For example: "update_unbilled_only":true. Default: false |
| update_existing_hours_internal_rate | Specifies if the updated internal hour rate should be applied to existing hours. For example: "update_existing_hours_internal_rate":false. Default: true |
| update_unbilled_hours_internal_rate | Specifies if the updated internal hour rate should only be applied to unbilled hours. This is ignored if "update_existing_hours_internal_rate" is false. For example: "update_unbilled_hours_internal_rate":true. Default: false |
| team_ids | Specifies the teams that the user will be part of, should be array of numerical team id's. Example values: team_ids: [3,4,2] |
| add_team_users_to_projects | Specifies if the user should be added to team projects Specified in team_ids. For example: "add_team_users_to_projects":false. Default: true |
| remove_team_users_from_projects | Specifies if the user should be removed from team projects not specified in team_ids. For example: "remove_team_users_from_projects":true. Default: false |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 1341,
"email": "marijawebtniwy@timelyapp.com",
"name": "Marija Petrovic",
"active": false,
"day_view_onboarded": true,
"memory_onboarded": true,
"created_at": 1747124513,
"updated_at": 1747124513,
"last_received_memories_date": null,
"sign_in_count": null,
"external_id": null,
"time_zone": "Europe/Paris",
"memory_retention_days": null,
"avatar": {
"large_retina": "https://www.gravatar.com/avatar/adba0b1e67e9b6ac5ca6fbbd0a3d5f74?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"large": "https://www.gravatar.com/avatar/adba0b1e67e9b6ac5ca6fbbd0a3d5f74?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_large_retina-c403e04ad44c7d8b8c7904dc7e7c1893101f3672565370034edbe3dee9985509.jpg&s=200",
"medium_retina": "https://www.gravatar.com/avatar/adba0b1e67e9b6ac5ca6fbbd0a3d5f74?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"medium": "https://www.gravatar.com/avatar/adba0b1e67e9b6ac5ca6fbbd0a3d5f74?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_medium_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=50",
"small_retina": "https://www.gravatar.com/avatar/adba0b1e67e9b6ac5ca6fbbd0a3d5f74?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25",
"small": "https://www.gravatar.com/avatar/adba0b1e67e9b6ac5ca6fbbd0a3d5f74?d=http%3A%2F%2Fapp.timelyapp.local%3A3002%2Fassets%2Fthumbs%2Fuser_small_retina-459a8b7582a7417f4b47a0064f692ffcd161fb11eda9dcc359f1b5e63fe51235.jpg&s=25"
},
"type": "User",
"work_days": "MON,TUE,WED,THU,FRI",
"weekdays": "MO,TU,WE,TH,FR",
"weekly_capacity": 40.0,
"user_level": "admin",
"admin": true,
"hide_hourly_rate": false,
"hide_internal_hourly_rate": false,
"deleted": false,
"default_hour_rate": 0.0,
"internal_hour_rate": 0.0,
"role_id": 2447,
"role": {
"id": 2447,
"name": "admin"
}
}
Webhooks
Webhooks allow external services to be notified when certain events happen. When the specified events happen, we’ll send a POST request to each of the URLs you provide.
Create a webhook
Request
curl "https://api.timelyapp.com/1.1/617/webhooks" -d '{"webhook":{"url":"https://marks.biz/melodi_schaden","subscriptions":["projects:created"],"active":true,"secret_token":"deadbeef"}}' -X POST \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer uY-QTYkgldRgFDPYDVWiuijZVsS28bKX30HitRrStLc" \
-H "Cookie: "
Endpoint
POST /1.1/:account_id/webhooks
POST /1.1/617/webhooks
Accept: application/json
Content-Type: application/json
Authorization: Bearer uY-QTYkgldRgFDPYDVWiuijZVsS28bKX30HitRrStLc
Parameters
{"webhook":{"url":"https://marks.biz/melodi_schaden","subscriptions":["projects:created"],"active":true,"secret_token":"deadbeef"}}
| Name | Description |
|---|---|
| url required | The URL of the endpoint that will receive the webhook POST requests. (HTTPS required) |
| secret_token | Setting a webhook secret allows you to ensure that requests sent to the above webhook endpoint are from us. You'll receive a signature in the X-Signature header value. Calculate a SHA256 hash for the received payload using your provided SECRET_TOKEN on your end, and ensure that the result matches the X-Signature value. |
| subscriptions | Specifies the array of events should it listen to. The format is ['entity:action', ...]. Eg. ['project:created']. Use the wildcard (*) character for all events or all actions of an entity. Support subscriptions:
|
| active | By default, webhook deliveries are active. You can choose to disable the delivery of webhook payloads by disable this. |
Response
Content-Type: application/json; charset=utf-8
201 Created
{
"id": 2,
"account_id": 617,
"url": "https://marks.biz/melodi_schaden",
"subscriptions": [
"projects:created"
],
"secret_token": "deadbeef",
"active": true,
"created_at": "2025-05-13T10:21:55+02:00",
"updated_at": "2025-05-13T10:21:55+02:00"
}
Delete a webhook
Request
curl "https://api.timelyapp.com/1.1/618/webhooks/3" -d '' -X DELETE \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer y49Hw2EcBQM50Gl6HvX1JnoauPrFE8dk9x1PS9VtoJ8" \
-H "Cookie: "
Endpoint
DELETE /1.1/:account_id/webhooks/:id
DELETE /1.1/618/webhooks/3
Accept: application/json
Content-Type: application/json
Authorization: Bearer y49Hw2EcBQM50Gl6HvX1JnoauPrFE8dk9x1PS9VtoJ8
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the webhook you want to delete |
| id | The ID of the webhook you want to delete |
Response
Content-Type: application/json; charset=utf-8
200 OK
{}
List all webhooks
Request
curl -g "https://api.timelyapp.com/1.1/620/webhooks" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer mkPFLOo_X9c3k4_uAzIlZkVFUbDA40x5sCXlhbioQI4" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/webhooks
GET /1.1/620/webhooks
Accept: application/json
Content-Type: application/json
Authorization: Bearer mkPFLOo_X9c3k4_uAzIlZkVFUbDA40x5sCXlhbioQI4
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the webhooks you want to retrieve |
| offset | Retrieve webhooks from offset |
| limit | Retrieve number of webhooks |
Response
Content-Type: application/json; charset=utf-8
200 OK
[]
Retrieve a webhook
Request
curl -g "https://api.timelyapp.com/1.1/619/webhooks/4" -X GET \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer V6VNDdm88xUkKtc63kq8ysZWyxB7hgRyOXMBP6dhJRU" \
-H "Cookie: "
Endpoint
GET /1.1/:account_id/webhooks/:id
GET /1.1/619/webhooks/4
Accept: application/json
Content-Type: application/json
Authorization: Bearer V6VNDdm88xUkKtc63kq8ysZWyxB7hgRyOXMBP6dhJRU
Parameters
| Name | Description |
|---|---|
| account_id | The account ID containing the webhook you want to retrieve |
| id | The ID of the webhook you want to retrieve |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 4,
"account_id": 619,
"url": "https://lesch.net/thaddeus_hayes",
"subscriptions": [
"projects:created"
],
"secret_token": null,
"active": true,
"created_at": "2025-05-13T10:21:55+02:00",
"updated_at": "2025-05-13T10:21:55+02:00"
}
Update a webhook
Request
curl "https://api.timelyapp.com/1.1/621/webhooks/5" -d '{"webhook":{"subscriptions":["projects:created","labels:created"],"secret_token":"deadbeef"}}' -X PUT \
-H "Version: HTTP/1.0" \
-H "Host: api.timelyapp.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer cBnnb7ZvM8NIUOQq9T9lS7oetnUfL8auDSXU5-JjXxo" \
-H "Cookie: "
Endpoint
PUT /1.1/:account_id/webhooks/:id
PUT /1.1/621/webhooks/5
Accept: application/json
Content-Type: application/json
Authorization: Bearer cBnnb7ZvM8NIUOQq9T9lS7oetnUfL8auDSXU5-JjXxo
Parameters
{"webhook":{"subscriptions":["projects:created","labels:created"],"secret_token":"deadbeef"}}
| Name | Description |
|---|---|
| id required | Webhook ID |
| url required | The URL of the endpoint that will receive the webhook POST requests. (HTTPS required) |
| secret_token | Setting a webhook secret allows you to ensure that requests sent to the above webhook endpoint are from us. You'll receive a signature in the X-Signature header value. Calculate a SHA256 hash for the received payload using your provided SECRET_TOKEN on your end, and ensure that the result matches the X-Signature value. |
| subscriptions | Specifies the array of events should it listen to. The format is ['entity:action', ...]. Eg. ['projects:created']. Use the wildcard (*) character for all events or all actions of an entity. |
| active | Example values: "true" or "false" |
Response
Content-Type: application/json; charset=utf-8
200 OK
{
"id": 5,
"account_id": 621,
"url": "https://bruen-heaney.org/terrence_rogahn",
"subscriptions": [
"projects:created",
"labels:created"
],
"secret_token": "deadbeef",
"active": true,
"created_at": "2025-05-13T10:21:56+02:00",
"updated_at": "2025-05-13T10:21:56+02:00"
}
Errors
Example responses:
422 Unprocessable Entity
{
"errors":{
"name":[
"can't be blank"
],
"project_users":[
"is invalid"
]
}
}
422 Unprocessable Entity
403 Forbidden
{
"errors":{
"message":"error message"
}
}
404 Not Found
{
"errors":{
"message":"Not Found"
}
}
401 Unauthorized
{
"errors":{
"message":"Unauthorized"
}
}
Timely uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed due to the information provided. Codes in the 5xx range indicate an error with Timely's servers.
Unauthorized access o projects and accounts, or trying to create or delete objects that are not under our control, will result in errors.
The Timely API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 - Bad Request | Your request is invalid |
| 401 - Unauthorized | Wrong authentication token was used |
| 403 - Forbidden | The entity requested is hidden from unauthorized access |
| 404 - Not Found | The specified entity could not be found |
| 422 - Unprocessable Entity | The server understands the content type, but was unable to process the request |
| 500 - Internal Server Error | We’re experiencing a problem with our server. Try again later. |