Download our ebook

Weekdone API documentation

Weekdone API is RESTful interface, providing access to the data in Weekdone system.
The API supports JSON output.

Overview

Weekdone API is RESTful interface, providing access to most of the data in the system.

The API accepts form-encoded content and query parameters in requests and all responses are encoded in JSON, including errors. UTF-8 is the only character encoding supported for both requests and responses.

Authentication

All API requests must contain way to authenticate the user and authorize access to requested data. Weekdone API supports OAuth 2.0 Authentication mechanism. A web application with a user's authorization key, may access information and make changes to data stored in Weekdone as if it were that user.

OAuth 2.0

Weekdone API supports only Authorization Code Grant flow of the OAuth 2.0 framework. This is the most common strategy for traditional web applications and native desktop/mobile apps.

Registering your application

Before starting to implement the Weekdone API a new app must be registered with Weekdone to receive Client ID and Client Secret. This can be done from Applications page. All applications added by a client are visible to all admin level accounts of that client.

As with all OAuth apps, you must supply an Application URL as well as a Redirect URL that successful (or failed) authentications will redirect to.

Requesting authorization from the user

Developers should use button with the text "Sign in with Weekdone" when redirecting users to Weekdone to start authorization flow.

To start the authorization flow users must be redirected to https://weekdone.com/oauth_authorize passing parameters in query string.

Name Required Description
client_id yes The Client ID uniquely identifies the application making the request.
redirect_uri yes The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings.
response_type yes Must be 'code' (as other authorization flows are not supported).
state no Encodes state of the app, which will be returned verbatim in the response and can be used to match the response up to a given request.
If either the client_id or redirect_uri do not match, the user will simply see a plain-text error. Otherwise, all errors will be sent back to the redirect_uri specified.

The user then sees a screen giving them the opportunity to accept or reject the request for authorization. In either case, the user will be redirected back to the redirect_uri.

Response back to application

User will be redirected back to redirect_uri with following parameters in the query string on successful authorization:

Name Description
code This is the code your app can exchange for a token
state The state parameter that was sent with the authorizing request

Token exchange

If user granted access to the application the code received by application must be exchanged for proper access token. The app must make POST request to https://weekdone.com/oauth_token passing following parameters in form-encoded post body:

Name Required Description
code yes The code you are exchanging for an auth token
grant_type yes Must be authorization_code
client_id yes The Client ID uniquely identifies the application making the request.
client_secret yes The Client Secret belonging to the app, found in application details
redirect_uri yes Must match the redirect_uri specified in the original request

Token exchange response

In the response, you will receive a JSON payload with the following parameters:

Name Description
access_token The token to use in future requests against the API
refresh_token If exchanging a code, a long-lived token that can be used to get new access tokens when old ones expire.
user A JSON object encoding a few key fields about the logged-in user

Requesting new access token with refresh token

access_token will expire in 60 minutes and new tokens must be requested using refresh_token. To request new access token the app must make POST request to https://weekdone.com/oauth_token passing following parameters in form-encoded post body:

Name Required Description
refresh_token yes The refresh_token
grant_type yes Must be refresh_token
client_id yes The Client ID uniquely identifies the application making the request.
client_secret yes The Client Secret belonging to the app, found in application details
redirect_uri yes Must match the redirect_uri specified in the original request
Response will be the new access_token

Tips to get you started

There are several OAuth libraries to get you started

We have Zapier integration available if you are already using Zapier

Items

Items are what reports are made of. Each item may belong to one or several reports and evey item has following parameters:

Name Type Description
id number Uniquely identifies each item
inserted datetime When the item was added to Weekdone
description string The textual description of the item
type_id number In which report category the item belongs to:
0 = Plans on Hold
1 = Progress
2 = Plans
3 = Problems
4... = Custom types
user_id number ID of user who added the task or to whom the task was assigned
team_id number ID of the team where item was added
source number Source of the item 0 = Weekdone
1 = JIRA
2 = Asana
3 = Basecamp
4 = GoogleTasks
5 = Slack
source_id string ID of the item in external system. Maximum length is 50 characters
priority number 0 = not specified
1 = green
2 = amber
3 = red
commentcount number Number of comments
likecount number Number of likes
from_id number Who assigned this item
due_on date When the item is due
private number Who can see the item
0 - public: item has team permissions
1 - private: item is only visible to owner

Each report in Weekdone is identified by it's number. The number is in form YYYYWW where YYYY is the year and WW is the week number.

Name Type URL Sample response:
Search for items GET https://api.weekdone.com/1/items?token=<OAuth Token> 
{
  "status": "ok",
  "items": [
    {
      "id": 690,
      "inserted": "2013-03-28T13:37:54Z",
      "description": "item is here",
      "likecount": 0,
      "commentcount": 0,
      "type_id": 2,
      "team_id": 3,
      "user_id": 12,
      "priority": 1,
      "from_id": 144,
      "source": 0,
      "due_on": "2014-02-02"
    }
  ]
}
Search parameters
Name Description
user_id Search by user ID. Special alias 'me' can be used instead of currently authenticated users ID.
team_id Search by team ID
period Search by week number. Defaults to current week
Create item POST https://api.weekdone.com/1/item?token=<OAuth Token>
Supported fields:
Name Required Description
description yes
type_id yes
period no Week where to add the item, defaults to current week
user_id no defaults to OAuth token owner
team_id no defaults to OAuth token owner primary team ID
priority no
source_id no ID of the item in external system
due_on no
private no defaults to 0 (public)
Update item PUT https://api.weekdone.com/1/item/<item ID>?token=<OAuth Token>
Supported fields:
Name Description
description
type_id Move item to different category
period Required when updating type_id
priority
due_on
Assign item to another user PUT https://api.weekdone.com/1/item/<item ID>/assign?token=<OAuth Token>
Supported fields:
Name Required
user_id yes
Delete item DELETE https://api.weekdone.com/1/item/<item ID>?token=<OAuth Token>
Get item likes GET https://api.weekdone.com/1/item/<item ID>/likes?token=<OAuth Token> Sample result 
{
  "status": "ok",
  "likes": [
    {
      "id": 1360,
      "name": "John Doe"
    }
  ]
}
Add item like POST https://api.weekdone.com/1/item/<item ID>/likes?token=<OAuth Token>
Delete item like DELETE https://api.weekdone.com/1/item/<item ID>/likes?token=<OAuth Token>
Sort items PUT https://api.weekdone.com/1/item/<item ID>/sort?token=<OAuth Token>
Supported fields:
Name Required
type_id yes
list yes Comma separated list of item ID's in this category
period yes Which week to sort
Get item comments GET https://api.weekdone.com/1/item/<item ID>/comments?token=<OAuth Token> Sample result 
{
  "status": "ok",
  "comments": [
    {
      "id": 1360,
      "inserted": "2014-02-28T13:37:54Z",
      "comment": "this is item comment",
      "user_id": 12
    }
  ]
}
Add item comment POST https://api.weekdone.com/1/item/<item ID>/comments?token=<OAuth Token>
Supported fields:
Name Required
comment yes
Delete item comment DELETE https://api.weekdone.com/1/item/<item ID>/comments/<comment ID>?token=<OAuth Token>

Report

Get weekly report data grouped by teams. See Items and Users for list of parameters

Each report in Weekdone is identified by it's number. The number is in form YYYYWW where YYYY is the year and WW is the week number. Defaults to current week.

Name Type URL Sample response:
Get report GET https://api.weekdone.com/1/report?token=<OAuth Token> 
{
  "status": "ok",
  "period": "201504",
  "report": [
    {
      "id": 1,
      "name": "Default Team",
      "users": [
        {
          "id": 1,
          "name": "User name",
          "items": [],
          "rate": null,
          "reviews": [],
          "ratings": {
            "333":5
          }
        },
        {
          "id": 2,
          "name": "Second Testuser",
          "items": [],
          "rate": 5,
          "reviews": [],
          "ratings": []
        }
      ]
    }
  ]
}
Search parameters
Name Description
user_id Search by user ID. Special alias 'me' can be used instead of currently authenticated users ID.
team_id Search by team ID
period Search by week number. Defaults to current week

Teams

Each company account on Weekdone has one or move teams, which have following parameters:

Name Type Description
id number Uniquely identifies each team
name string
privacy number Who may see team reports
1 = everybody in the company
1 = team members
2 = team manager only
external_reports string Additional addresses to whom team reports are sent
Following fields exist when each team uses it's own template
rate_question string Question for rating week with 5 stars
reportsdue_day number Weekday when the report will be sent
reportsdue_hour number Time of day when the report will be sent
reportreminder_day number Weekday when the report reminders will be sent
reportreminder_hour number Time of day when the report reminders will be sent
timezone string Timezone of the team. Used to calculate reportsdue and reportreminder values
Name Type URL Sample response:
Get all teams GET https://api.weekdone.com/1/teams?token=<OAuth Token> 
{
  "status": "ok",
  "teams": [
    {
      "id": 3,
      "name": "Arendustiim",
      "privacy": 3,
      "external_reports": "external@example.com"
    }
  ]
}

Users

User object has following fields

Name Type Description
id number Uniquely identifies each user
inserted datetime When the item was created
admin number Whether this is company level admin
team_id number User's primary team
teams array All teams user belongs to. Each user has two parameters in each team: observer and admin
Name Type URL Description
Get all users GET https://api.weekdone.com/1/users?token=<OAuth Token> Example: 
{
  "status": "ok",
  "users": [
    {
      "id": 1,
      "name": "Test User",
      "picture": "http://weekdone.com/favicon2.php?i=T",
      "admin": 0,
      "team_id": 1,
      "teams": [
        {
          "id": 1,
          "name": "Testing Team",
          "observer": 0,
          "admin": 0
         }
      ]
    }
  ]
}

Types

Reports are divided into types. When all teams in company use different templates, then team_id will be present. Types may have following fields:

Name Type Description
id number ID of the type. There are three pre-defined types which all reports have:
1 = Progress
2 = Plans
3 = Problems
There is one special type with ID=0 - this is carryover category for 'Plans' (ID=2). Items cannot be added there.
name string Name of the type
carryover boolean Whether items in this category will carry over to next week
overdue boolean When items carry over to next week, whether to count items as overdue when they have been carried over more than twice

Name Type URL Description
Get all types GET https://api.weekdone.com/1/types?token=<OAuth Token> Example: 
{
  "status": "ok",
  "same_template": false,
  "types": [
    {
      "id": 0,
      "team_id": 1,
      "name": "In progress"
    },
    {
      "id": 1,
      "team_id": 1,
      "name": "Progress"
    },
    {
      "id": 103,
      "team_id": 1,
      "name": "Custom item type",
      "carryover": true,
      "overdue": false
    }
  ]
}

Tags

Tags added to elements. Optional field "status"

Name Type URL Description
Get all tags GET https://api.weekdone.com/1/tag?token=<OAuth Token> Example: 
{
  "status": "ok",
  "tags": [
    {
      "id": 23,
      "tag": "design",
      "status": {
        "status": "Design is on track",
        "updated": "2015-01-05 11:33:21",
        "user_id": 321232
      }
    },
    {
      "id": 44,
      "tag": "website"
    }
  ]
}
Get single tag GET https://api.weekdone.com/1/tag/<tag ID>?token=<OAuth Token> Example: 
{
  "status": "ok",
  "tag": {
    "id": 32,
    "tag": "products",
    "status": {
      "status": "Products are on time",
      "updated": "2015-04-02 12:51:22",
      "user_id": 531232
    }
  }
}
Update TAG priority POST https://api.weekdone.com/1/tag/<tag ID>/priority?token=<OAuth Token>
Supported fields:
Name Required Description
priority yes 0 - this is not priority tag, 1 - this is a priority tag
Update TAG status POST https://api.weekdone.com/1/tag/<tag ID>/status?token=<OAuth Token>
Supported fields:
Name Required Description
status yes

Objectives

There are four level of Objectives: Company, Department, Team and Personal. All Objectives have almost same columns with following exceptions

  • Department Objective has department_id
  • Team Objective has team_id
  • Personal Objective has team_id and user_id
"progress" field of Objectives is calculated based on Key Results "progress" and therefore cannot be updated directly.
Name Type Description
id number ID of the Objective
type string Type of Objective (company, department, team, user)
description string Description of the Objective
period string Quarter of the Objective in form YYYYQ
comments number Number of comments
progress number Percentage of Objective completion
results array List of Key Results
parent_list array List of parent Objectives

Key Results

Name Type Description
id number ID of the Key Result
result string Key Result description
inserted datetime Key Result creation time
type string Type of Key Result (default %)
startval number Key Result minumum value
maxval number Key Result maximum value
weight number Key Result weight -4...+4
progress number Key Result progress
updated datetime Last Key Result progress update date
user_id number ID of user who updated Key Result progress
comments array List of Key Result comments
Name Type URL Description
Get all Objectives GET https://api.weekdone.com/1/objective?token=<OAuth Token> Example: 
{
  "status": "ok",
  "data": [
    {
      "id": 1,
      "description": "Reach the goal"
      "type": "company",
      "progress": 60,
      "results": [
        {
          "id": 1,
          "result": "Do important things 5 times",
          "type": "times",
          "weight": 1,
          "progress": 3,
          "startval": 0,
          "maxval": 5,
          "commentcount": 0,
          "comments": []
        }
      ]
    }
  ]
}
Search parameters
Name Description
type Return specific type of objectives (company, department, team, user)
department_id Return department objectives
team_id Return team objectives
user_id Return user objectives
period Return objectives for period: YYYYQ or YYYY
Create new Objective POST https://api.weekdone.com/1/objective?token=<OAuth Token>
Supported fields:
Name Required Description
type yes Objective type (company, department, team, user).
  • Department requires field department_id
  • Team requires field team_id
  • User requires fields team_id and user_id
description yes
period no Defaults to current quarter. In format YYYYQ
Update Objective POST https://api.weekdone.com/1/objective/<objective_id>?token=<OAuth Token>
Supported fields:
Name Required Description
description yes
Delete Objective DELETE https://api.weekdone.com/1/objective/<objective_id>?token=<OAuth Token>
List Objective comments GET https://api.weekdone.com/1/objective/<objective_id>/comments?token=<OAuth Token>
Add Objective comment POST https://api.weekdone.com/1/objective/<objective_id>/comments?token=<OAuth Token>
Update Objective comment POST https://api.weekdone.com/1/objective/<objective_id>/comments/<comment_id>?token=<OAuth Token>
Delete Objective comment DELETE https://api.weekdone.com/1/objective/<objective_id>/comments/<comment_id>?token=<OAuth Token>
Add Objective result POST https://api.weekdone.com/1/objective/<objective_id>/result?token=<OAuth Token>
Supported fields:
Name Required Description
description yes Key Result description
Update Objective result POST https://api.weekdone.com/1/objective/<objective_id>/result/<result_id>?token=<OAuth Token>
Supported fields:
Name Required Description
description no
progress no Update progress of Key Result in current period
Delete Objective result DELETE https://api.weekdone.com/1/objective/<objective_id>/result/<result_id>?token=<OAuth Token>

Company details

Each company has several configuration settings:

Name Type Description
same_schedule boolean Whether all teams use the same schedule
same_template boolean Whether all teams use the same template
external_emails string List of e-mail addresses where company reports are sent
company_objectives boolean Whether company objectives are used
team_objectives boolean Whether team objectives are used
user_objectives boolean Whether personal objectives are used
Following fields are only present when same_schedule=true
reportsdue_day number Weekday when reports will be sent
reportsdue_hour number Time of day when reports will be sent
reportreminder_day number Weekday when report reminders will be sent
reportreminder_hour number Time of day when report reminders will be sent
timezone string Timezone of the company. Used to calculate reportsdue and reportreminder values

Name Type URL Sample response:
Get company info GET https://api.weekdone.com/1/company?token=<OAuth Token> 
{
  "status": "ok",
  "data": {
    "same_schedule": true,
    "same_template": false,
    "external_emails": "",
    "company_objectives": 1,
    "team_objectives": 1,
    "user_objectives": 1,
    "reportsdue_day": 5,
    "reportsdue_hour": 19,
    "timezone":"US/Hawaii"
  }
}

Responses

Status Response
202 {"status":"ok"}
400 {"status":"error"} - Invalid request, this usually occurs due to missing or invalid parameters in the request.
401 {"status":"error"} - No authorization is returned when no valid API key was supplied.
403 {"status":"error"} - Forbidden, when OAuth authenticated user does not have permission to access this resource.
404 {"status":"error"} - Not found is returned when request method and path are uknown.
500 {"status":"error"} - Internal Server error, means that a problem occurred in Weekdone system. This will usually resolve by itself but if consistent, please contact hello@weekdone.com